If you build

Five packages, one source. Which one is yours depends on what the page is, not on taste — and the other four are built on the first, so nothing you install disagrees with anything else you install.

Package	Version	For	What it is
`@pepperui/tokens`	1.5.0	everything — the other four are built on it	Pepper UI design tokens — the Mobupps design system. One source, seven outputs: CSS, SCSS, a Tailwind v3 preset, a Tailwind v4 theme, the shadcn variable map, Figma-import JSON and a Python module.
`@pepperui/css`	2.3.1	The deck tool, site prototypes, Laravel Blade, quarter builder	Pepper UI components as framework-free CSS — the Mobupps design system for the deck tool, the site’s Blade and prototype pages and the quarter builder. Ships the icon library too: every Figma Icon/* glyph as one SVG sprite and per-icon files, and the brand and award marks. Every class is built on @pepperui/tokens; no literal colour anywhere (stylelint).
`@pepperui/react`	0.0.0	the products	Pepper UI React components, distributed as a shadcn registry on Base UI. registry.json is the canon: one item per component, its props typed from the Figma component properties and its contract in `meta`. Implemented items (registry/&lt, item&gt, /&lt, item&gt, .tsx) install with `npx shadcn add @pepperui/<item>`; the rest install their typed props until their screen comes.
`@pepperui/charts`	1.1.5	The deck tool, quarter builder, PPTX export, Figma recipes	The Mobupps design system’s chart theme: per-accent series palettes, the two-slice donut rule, the narrow-band axis floor and the shared number-format object, generated from @pepperui/tokens. One palette, four renderers — ECharts, Chart.js, the PPTX exporter and the Figma chart recipes.
`@pepperui/illustrations`	0.8.0	The design lead and managers for slides and PDFs, the site, and later anyone in the team through Claude Design	The Mobupps design system’s illustration library: isometric scenes built from one library of objects, each placed on a page by name with <pepper-illustration scene=“…”>. A small element paints the scene’s still (drawn at build time in every palette and direction, the design system’s Poppins inside) and loads the three.js engine only when a picture has to move — one shared WebGL renderer for every live picture on the page.

Install

Four install from npm. A version on the registry is always a version this repository tags — the tag is cut first and the publish is of that same commit — so the number in the table above is the number that installs, and the Changelog says what has changed in it since. The React side installs from the repository’s own registry.

npm install @pepperui/tokens

Then, in CSS:

@import "@pepperui/tokens/css";

shadcn and Tailwind v4 gain two lines beside it — both references into tokens.css, never values:

/* the app's Tailwind v4 entry */
@import "tailwindcss";                    /* or theme.css + utilities.css without preflight — see artifacts/pilots/mafo */
@import "@pepperui/tokens/css";           /* --pui-* */
@import "@pepperui/tokens/shadcn";        /* --primary, --ring, --muted… = Pepper roles (build/shadcn-map.json), + @theme */
@import "@pepperui/tokens/tailwind.css";  /* every scale as a pui- key: rounded-pui-16, text-pui-14, bg-pui-surface-card */

npm install @pepperui/tokens @pepperui/css

The tokens are a peer dependency, not a dependency: they install beside the components, so a project has one copy of --pui-* and not two. Load them first. One file, no build step:

<link rel="stylesheet" href="node_modules/@pepperui/tokens/dist/tokens.css">
<link rel="stylesheet" href="node_modules/@pepperui/css/dist/pepper-ui.css">

or, with a bundler:

@import "@pepperui/tokens/css";
@import "@pepperui/css";

35 of the 88 items are React components on Base UI today; the rest install their typed props and contract until their screen comes (one screen at a time). Installed the shadcn way, from the private repository, through a read-only access token exported in the shell — never written into components.json:

"registries": {
  "@pepperui": {
    "url": "https://api.bitbucket.org/2.0/repositories/rashidmobupps/pepper-ui/src/main/packages/react/public/r/{name}.json",
    "headers": { "Authorization": "Bearer ${BITBUCKET_REGISTRY_TOKEN}" }
  }
}

npx shadcn add @pepperui/button

npm install @pepperui/charts

It carries the palette, not the renderer — bring your own ECharts or Chart.js:

<script src="…/echarts.min.js"></script>
<script src="…/pepper-charts.js"></script>

<div class="echart" data-chart style="position:relative;width:760px;height:380px">
  <script type="application/json">
    {"type":"bar","labels":["Jan","Feb","Mar"],
     "datasets":[{"label":"Revenue","data":[820000,1044000,310500]}],
     "axis":{"fmt":{"style":"compact","prefix":"$"}}}
  </script>
</div>

Or, for a chart you configure yourself:

import { buildOption, echartsTheme, valueFormatter } from '@pepperui/charts';

echarts.registerTheme('pepper-red', echartsTheme('red'));      // defaults for a hand-written chart
chart.setOption(buildOption(cfg, { w: el.clientWidth, h: el.clientHeight }));

npm install @pepperui/illustrations

Serve its dist/ folder as it is — the element finds its engine and its stills beside its own script — and place a scene by its name:

<pepper-illustration scene="cross-screen" palette="red" label="One user across three screens"></pepper-illustration>
<script src="node_modules/@pepperui/illustrations/dist/pepper-illustration.js"></script>

The attributes, and what a page pays for a moving picture, are on Exporting.

The first component on a page

Load the tokens, then the components — the two <link> lines in the CSS tab above. Poppins is not loaded by the package; packages/fonts/fonts.css carries the @font-face rules if the page has none.
Give the page its accent. The accent roles resolve only under a mode — a card icon on accent/main paints nothing until the shell says which accent it is, so the page, or the shell, sets it once:
```
<body data-accent="red">  </body>
```

Paste the markup block from the top of button.css. Every stylesheet in @pepperui/css opens with the markup to copy and the modifier list — the same block the Button page shows:

<button class="pui-button">Save</button>
<button class="pui-button pui-button--secondary pui-button--small">
  <span class="pui-icon pui-button__icon">…lucide svg…</span>Back</button>
<a class="pui-button pui-button--ghost" href="…">Skip</a>

You should see this. The frame below is the workshop’s own Button story, rendered here — every size and every state of the class you just wrote, and the same story the visual gate shoots on every commit.

Button — every size and every stateOpen in the workshop

The default option needs no modifier: .pui-button is the primary, medium button.

The three rules the build enforces

Never type a colour. Every value is var(--pui-…); a literal hex in the package fails its own build (stylelint — no hex, no named colour, no rgb()), and the pilots swept the consumers’ stylesheets the same way. A value the system has no token for is a question for the intake, not an override.
The class grammar is fixed. pui- prefix plus BEM: the block is the registry item’s name, a modifier is the Figma option verbatim (.pui-button--secondary, .pui-input--small), a part is __, and a state is the browser’s or the ARIA attribute your script sets (:hover, [aria-invalid="true"], [data-state="open"]). It sits beside Bootstrap, CoreUI and your own CSS without a collision.
A Pepper element carries only Pepper classes. On a Bootstrap page a button is pui-button, never btn pui-button; a consumer’s tag resets are kept off Pepper classes through a :where() guard.

If a coding agent builds your UI

Hand it DESIGN.md at the root of the repository — the whole system in one file, in the format coding agents read before they build UI. It is generated from the tokens and linted in CI, so it cannot be stale. AGENTS.md is the short note beside it, and these are its six instructions, in its order:

Read DESIGN.md.
Use tokens, never values.
Open the component’s contract before composing it.
On a page that is not React, use @pepperui/css
On React, install from the registry, never re-write
Prefer an existing component to new markup.

What is measured for you

Each component’s page ends with its measured accessibility rows — the contrast pairs its stories render, its focus indicator against what those pixels showed before focus, and the keyboard contract its role implies; the instruments are on the Accessibility page. In the repository, npm test holds the rest: no literal colour, every built output current, Figma name = code name = doc name, the locked rules as tests rather than prose, and this site regenerated and compared with its sources.

Worked examples — the pilots

A consumer is never written to: each adoption was done in a copy under artifacts/pilots/, delivered as a diff, and gated with before-and-after renders. The READMEs are the migration notes a product’s own adoption will follow — what moved, what was substituted and stated, what the gates found.

Consumer	Migration notes
the dashboard skill	README-2.4.7.md · README-3.1.4.md
MAFO `client`	README-2.5.8.md · README-2.5.9.md · README-2.7.10.md · README-2.7.11.md · README-2.7.3.md · README-2.7.6.md · README-3.5.5.md · README-3.9.3.md · README.md
The deck tool	README-2.4.3.md · README-2.4.5.md · README-2.4.7.md · README-2.4.8.md · README-2.5.10.md · README-3.1.1.md · README-3.1.3.md · README.md
the quarter builder	README-2.4.7.md · README-3.1.2.md
the site — prototypes	README-2.4.1.md · README-2.4.6.md · README-2.4.7.md · README-2.5.10.md
the site — Blade	README-2.4.2.md · README-2.4.6.md · README-2.4.7.md · README-2.4.8.md · README-2.5.10.md
skills	README-2.6.2.md
web-sections	README-3.10.2.md