Sapphire UI

Navy and gold, product and editorial typography, one CSS contract. Use Sapphire as plain HTML classes, Tailwind tokens, typed React components, or vendored registry source. Fonts ship with the package. CSS and native elements need no React dependency.

Catalogue · Design · Package contract · Registry · Migration · Changelog

Version 4.1 includes API and theme changes from 4.0. Follow the migration guide before updating an existing application.

bun add @kongmy-dev/sapphire-ui

HTML classes

Import the full stylesheet through your bundler:

@import '@kongmy-dev/sapphire-ui/sapphire.css';

<button class="sp-button" data-variant="brand">Save</button>
<article class="sp-card"><h2>Account</h2><p>Shared styles, native markup.</p></article>

Use the catalogue's HTML snippets for static markup. A snippet of a React portal cannot implement its overlay interaction; use its React component or your own behaviour.

Tailwind tokens

Compile your utilities against Sapphire's token mapping:

@import 'tailwindcss';
@import '@kongmy-dev/sapphire-ui/tailwind.css';
@import '@kongmy-dev/sapphire-ui/sapphire.css';

<p class="text-muted-foreground">Quiet copy</p>

Utilities override component-layer styles. --brand is decorative gold; --brand-text is the token for readable gold text.

React

Install react and react-dom. Interactive primitives also use the optional radix-ui peer; SplitLayout uses optional react-resizable-panels.

import { Button } from '@kongmy-dev/sapphire-ui/button';
import { Card } from '@kongmy-dev/sapphire-ui/card';
import '@kongmy-dev/sapphire-ui/sapphire.css';

export function Account() {
  return <Card><Button variant="brand">Save</Button></Card>;
}

Use public subpaths; there is no JavaScript root barrel or CommonJS build. Icons accept React SVG elements. Basic components do not load Radix.

Registry

Initialize an existing Vite/Tailwind app with the base and map @sapphire to https://design.kongmy.dev/r/v4/{name}.json in components.json:

bunx --bun [email protected] init https://design.kongmy.dev/r/v4/base.json --yes
bunx --bun [email protected] add @sapphire/button @sapphire/dialog @sapphire/sidebar

The base imports foundations and bundled fonts. Each vendored component owns its local CSS. In a mixed app, import foundations.css plus only the package component CSS still in use. Give each component one JavaScript and CSS owner. The existing /r/ registry remains frozen; moving to /r/v4/ is explicit.

Customization

Use props and data attributes first, then utilities or consumer classes, then component --sp-* variables, then shared token overrides. Vendor a component when the app needs to own its implementation. Do not load its package CSS alongside the vendored CSS or combine the full stylesheet with mixed ownership.

Override colours on every theme scope so nested light/dark sections keep working:

:root, [data-theme="light"], [data-theme="dark"], .dark {
  --brand-text: light-dark(var(--primary), var(--on-dark));
}

Set data-theme="light" or data-theme="dark" on a scope. The theme helper exports initTheme, setTheme and subscriptions; the React theme-provider entry supplies reactive theme preferences. Call initialization in a browser; importing a module on the server does not initialize a document.

Native elements

import '@kongmy-dev/sapphire-ui/elements/toast';
import '@kongmy-dev/sapphire-ui/sapphire.css';

Native tags include sapphire-toast, cookie-banner, sapphire-analytics, sapphire-banner, sapphire-site-header and sapphire-site-footer. Import each entry to register its tag in a browser. Constructors are undefined during SSR. See the package guide for lifecycle and import contracts.

BSD 3-Clause License