Skip to main content
Normal UI

Normal
UI

The browser's own stylesheet, repaired to WCAG 2.2 AA.

Normal UI keeps the browser's built-in look (system font on white, blue underlined links, grey buttons, black text) and repairs it wherever it falls short of WCAG 2.2 AA. Nothing is added for decoration.

How the docs are organised

By atomic design: five levels, each built from the one before it. Every component page says what it is made of and where it is used.

Atoms (13)
The smallest parts: one control or element, with the label it needs to be usable. Split an atom any further and it stops meaning anything.
Molecules (17)
A few atoms working together as one unit with one job: a quantity stepper, a menu button, a breadcrumb trail.
Organisms (17)
Distinct sections of an interface, built from molecules and atoms, often with their own state and keyboard model: tabs, a data grid, a dialog.
Templates (9)
Page layouts with placeholder content: where the regions go, how they reflow, and the rhythm text follows. They show structure, not final content.
Pages (30)
Templates filled with real content, and their states: empty, loading, error and done. Pages are where the system is tested against the words and data it will actually hold.

Under them sit the foundations: the Guidelines (principles, colour, type, rhythm, controls and states, ARIA coverage), the Tokens every value comes from, and Typography, every text element as plain HTML renders it.

How the code is layered

  1. tokens.json is the source of every value. pnpm tokens writes src/styles/tokens.css (custom properties, both color schemes) and src/tokens.stylex.ts (StyleX constants pointing at them).
  2. src/styles/base.css styles the elements themselves, in the normal-ui layer. Write plain semantic HTML and it already looks right.
  3. src/components holds the React components. They add the wiring (labels, ARIA, keyboard) and style themselves with StyleX, whose atomic layers sit above the base layer.
  4. src/styles/patterns.css is the same composite styling for hand-written HTML (.pd-badge, [role=tab]…). The templates and pages use it.
  5. Themes restyle all of it from a few token values and element rules, switched with data-theme.