Installation

Install @master/ui, load its stylesheet and render a native element with a component class. If your project uses Master CSS, compile the package's source with your app styles. Otherwise, use the precompiled stylesheet; it supplies the components without Master CSS utilities.

#Set up Master CSS

For the source stylesheet, set up Master CSS 2.1 or later and its integration for your framework first. Follow the Master CSS installation guide for Vite, Astro, Next.js, Svelte and others.

#Install the package

npm install @master/ui --save-exact

Any package manager works, such as bun add @master/ui --exact or pnpm add @master/ui --save-exact. Master UI is experimental and any release may break what it published, so pin the version and upgrade on purpose; Stability says what to run after an upgrade.

#Import the stylesheet

Import Master UI after the Master CSS preset in your app stylesheet:

@import '@master/css';@import '@master/ui';

The preset declares the layer order theme, base, defaults, components, utilities. Master UI adds its rules to components, so utilities in your markup still win.

#Verify the installation

Make sure app.css is loaded by your app, then add a button to a rendered page. In JSX, write className instead of class:

<button type="button" class="btn btn-primary">Save changes</button>

Run the app through its existing development command. The button should have an ink face in light mode and a pale face in dark mode, with a visible keyboard focus ring. Its appearance needs no behavior script; saving changes still needs your application's action handler.

If it looks like an unstyled browser button, check that the page loads app.css and that the compiled output contains .btn. With source imports, verify that the Master CSS integration processes this stylesheet. Then check the markup.

#Import only what you use

Each component is also exported on its own. Import the shared theme first, then the components the app needs:

@import '@master/css';@import '@master/ui/theme.css';@import '@master/ui/components/button.css';@import '@master/ui/components/switch.css';

Include the stylesheets for all classes used by your markup. For example, a button containing an icon or spinner also needs that component's stylesheet. The full import avoids managing this list yourself.

#One import per stylesheet

The package comes with a small command line tool. init writes ui/index.css, which imports the theme and each stylesheet on a line of its own, and master-ui.json, which records what the project owns:

npx master-ui init

@import '@master/css';@import './ui/index.css';

Use this entry file in place of the full @master/ui import. It is optional: choose it when you want to maintain the import list or own selected component source. Delete a line only when your markup no longer uses its classes.

#Behaviors

Most components need no script. A few patterns have no native element (a combobox, a command palette, a calendar), and the package ships the reference script for each:

import { attach } from '@master/ui/behaviors'const detach = attach()

Call attach() in browser code after the markup exists. It attaches the patterns it recognizes at that moment and returns a cleanup function; call detach() before removing that markup. It does not observe later insertions or configure a context-menu target. See Behaviors for scoped attachment and individual functions. In React, Svelte or Vue, use the framework components to manage their lifetimes.

#Without Master CSS

The package includes components compiled to ordinary CSS. A bundler that supports CSS imports can use the installed, pinned package:

@import '@master/ui/base.css';@import '@master/ui/standalone.css';

base.css supplies the preset's reset, including box-sizing: border-box and form-control fonts. Omit that import if your project already provides an equivalent reset.

For a static page, copy the compiled files from the installed package into a directory your server exposes. For example, when public/ is served at /:

mkdir -p public/stylescp node_modules/@master/ui/dist/base.css public/styles/master-ui-base.csscp node_modules/@master/ui/dist/standalone.css public/styles/master-ui.css

<link rel="stylesheet" href="/styles/master-ui-base.css"><link rel="stylesheet" href="/styles/master-ui.css"><button type="button" class="btn btn-primary">Save changes</button>

The copied files come from the exact package version you installed. Copy them again when you intentionally upgrade that version. This route needs no CSS compilation in your app.

The compiled stylesheet declares the same layers and tokens as the source build. It follows the reader's color scheme; data-theme="light" or data-theme="dark" pins a scheme for the page or a subtree. It contains no Master CSS utilities: use your own CSS for layout, and replace utility classes when copying a layout, a block or a page.

#Check your markup

Each stylesheet has a contract: its classes, the element each goes on, and the attributes it needs. check reads your templates and reports what breaks one:

npx master-ui check

Run it from the project root with the package installed. It checks HTML and templates such as JSX, Svelte, Vue and Astro without rendering them. Resolve its diagnostics, then check the visible result and keyboard interaction in a browser; a clean static check does not establish accessibility or browser support. Working with AI covers diagnostics and CI use.

#Customize the theme

Use Theming to change shared values such as brand color, radius or focus color. Default theme explains their roles and defaults. If the change affects only one instance or one component, start with Customization to choose the right layer.