Installation
Constellation by Orbit Commerce is one package: tokens, styles, fonts, icons and React components. Import the stylesheet once, wrap the app in a tooltip provider, and every screen looks at home in Orbit Commerce.
Install
The whole kit is one package on npm.
@orbitcommerce/constellation 1.0.2React 19 and upnpm install @orbitcommerce/constellationReact and React DOM 19 are peer dependencies. Everything else comes with the package: the Radix primitives, cmdk, motion, Phosphor icons and the Fontsource fonts.
Add the styles
Import the fonts and the stylesheet once, at the root, after the app's own CSS.
// main.tsx
import './index.css' // the app's own styles first
import '@orbitcommerce/constellation/fonts.css'
import '@orbitcommerce/constellation/styles.css'Fonts
fonts.css loads Geist, Sora and Geist Mono, self-hosted through Fontsource (SIL Open Font License). A host that already ships Geist can load only what it is missing.
import '@orbitcommerce/constellation/fonts/sora.css'
import '@orbitcommerce/constellation/fonts/geist-mono.css'The optional base
The kit never resets the host page. An app that adopts it as its whole look adds .o-root to its root element; without it, components still look right and the host's own text, background and focus styles stay as they are.
<body className="o-root">
<App />
</body>| .o-root sets | To |
|---|---|
| Font, size, line height, colour | Geist at 14px, 1.45, Brand Ink |
| Background | The porcelain ground |
| Text rendering | Antialiased, with synthesised bold switched off |
| Caret and native controls | Orbit teal (caret-color, accent-color) |
| Selected text | A teal tint |
| Scrollbars | Thin, in the strong hairline colour |
| Keyboard focus | A 2px teal outline, 2px off every link, button and field inside it |
Icons
Icons come from the package's icons entry: Phosphor, re-exported so the set can be swapped for Orbit's own drawings later without touching product code. See Icons.
import { Button } from '@orbitcommerce/constellation'
import { PlusIcon } from '@orbitcommerce/constellation/icons'
<Button variant="primary" icon={<PlusIcon />}>Create order</Button>Dark theme
Light is the default. Dark applies under any of three markers on an ancestor, so the kit follows whichever toggle the host already has. Components read semantic tokens and never branch on the theme.
// Any one of these on <html> (or any ancestor) turns the kit dark.
document.documentElement.classList.add('dark')
document.documentElement.dataset.theme = 'dark'
document.documentElement.dataset.oTheme = 'dark'/* tokens.css */
:root, [data-theme='light'], [data-o-theme='light'] { /* light tokens */ }
.dark, [data-theme='dark'], [data-o-theme='dark'] { /* dark tokens */ }Each theme also sets color-scheme, so native scrollbars and form controls follow. To bring light back inside a dark page, use data-theme="light" or data-o-theme="light": there is no .light class.
Theme islands
ThemeScope makes a light or dark island inside a page of the other theme: a dark band on a light page, a preview. Menus, popovers, dialogs, tooltips and the command palette opened inside it follow the island, even though they are portalled out of it. Open the menu to see.
- Renders a
divwithdata-o-theme; every other prop goes to it. useThemeScope()returns the nearest island's theme, orundefinedwhen the page theme applies. Build portalled parts with it.
ThemeScope
| Prop | Type | Default | Description |
|---|---|---|---|
themeRequired | 'light' | 'dark' | None | The theme inside the island. |
Tooltip provider
Wrap the app in one TooltipProvider, near the root. It shares timing across tooltips: once one is open, its neighbours open instantly, which is what makes a toolbar feel quick. A lone tooltip brings its own provider, so nothing breaks without it; it is just slower.
import { TooltipProvider } from '@orbitcommerce/constellation'
createRoot(document.getElementById('root')!).render(
<TooltipProvider>
<App />
</TooltipProvider>,
)TooltipProvider
| Prop | Type | Default | Description |
|---|---|---|---|
delayDuration | number | 350 | Hover time in ms before the first tooltip opens. |
skipDelayDuration | number | 150 | Window in ms in which moving to another trigger opens its tooltip instantly. |
disableHoverableContent | boolean | None | Close as soon as the pointer leaves the trigger, even towards the tooltip. |
Vite and Next.js
The package ships ES modules and CommonJS with type definitions. In Vite, import and go. For React Server Components, the build adds a 'use client' banner to every bundle, because every component uses hooks: import components straight into Server Components and they render as client components.
// app/layout.tsx (Next.js App Router)
import './globals.css'
import '@orbitcommerce/constellation/fonts.css'
import '@orbitcommerce/constellation/styles.css'
import { TooltipProvider } from '@orbitcommerce/constellation'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en-GB">
<body className="o-root">
<TooltipProvider>{children}</TooltipProvider>
</body>
</html>
)
}Licence
- You may use Constellation by Orbit Commerce to build apps, plugins, themes and other software that work with Orbit Commerce.
- A stand-alone app, one that does not run inside Orbit Commerce, must look clearly different from Orbit Commerce's own products, including its dashboards.
- The licence does not cover Orbit Commerce's names or the Orbit logo, beyond saying where the kit comes from. Use the logo files only to refer to Orbit Commerce.
- The fonts and libraries the kit uses keep their own licences, such as the SIL Open Font License (Geist, Geist Mono and Sora) and MIT (Phosphor Icons and Radix UI).
Browser support
Chrome 125, Safari 16.4 and Firefox 128 or later. The kit relies on oklch(), color-mix(), @property and linear() easing.
Checklist
- Styles:
fonts.cssandstyles.css, imported once, after the app's own CSS. className="o-root"on the root, if the kit is the app's whole look.- One
TooltipProvidernear the root. - Dark theme through
.dark,data-themeordata-o-themeon an ancestor. - Icons from
@orbitcommerce/constellation/icons, never from Phosphor directly.