Reference

Stability

Identify public interfaces, control the source and theme your project uses, and review upgrades while Master UI is experimental.

On this page

A project depends on Master UI through class names, custom properties, imports and commands. Use the public interfaces below when building on the library, and review them when upgrading.

Master UI is experimental: even public interfaces may change in a 0.x release. Public identifies the supported way to use the current version; it does not promise compatibility with the next one. Upgrade deliberately to check the changes that affect your project.

#Public

What	Where it is stated	Example
Class names	`classes` in a contract	`btn`, `btn-primary`, `dialog-header`
The element and the attributes a class requires	`elements`, `attributes` and `label` of that class	`switch` goes on an `<input>` with `type="checkbox"` and `role="switch"`, and needs an accessible name
State marks	`states` in a contract	`aria-pressed="true"` on `btn`, `:checked` on `switch`
Custom properties of a component	`properties` in a contract	`--btn-height`, `--splitter-size`
Theme tokens	`@theme` in `theme.css`; `@master/ui/theme.json` lists each with its value	`--color-surface-raised`, `--radius-control`, `--lift`
Mixin names	`@mixin` in `theme.css`	`--surface-sheet`, `--focus-ring`, `--anchored`
The contract schema	`@master/ui/contract.schema.json`	The fields of a contract and what each means
The behaviors	The exports of `@master/ui/behaviors`	`combobox(root)`, `attach()`, `calendarMonth()`, the function each returns and its `value`
The names of the framework components	`frameworks/manifest.json`, which `master-ui add` reads	`combobox`, `dialog`, `toast`
The checker	The exports of `@master/ui/check`	`check`, `createIndex`, `parse`, `format`, `owners`
The commands	`master-ui`	`list`, `contract`, `check`, `init`, `own`, `add`, `status`, `diff`, `accept`
Import paths	`exports` in the package's `package.json`	The table below

A contract lists the interface for one component in the installed version. Print it before relying on a class or property:

npx master-ui contract button

The contract's properties list defines the component-specific extension points. Its unlisted internal properties may change. Shared theme tokens are a separate public interface, defined in theme.css.

#Import paths

Path	What it is
`@master/ui`, `@master/ui/master.css`	The theme, every component and the layout classes, as Master CSS source
`@master/ui/theme.css`	The tokens and mixins of the default theme
`@master/ui/components/<name>.css`, `@master/ui/layouts/<name>.css`	One stylesheet
`@master/ui/components/<name>.json`, `@master/ui/layouts/<name>.json`	Its contract
`@master/ui/themes/<name>.css`	Another theme, such as `paper`
`@master/ui/contract.schema.json`	The JSON Schema of a contract
`@master/ui/contracts.json`	Every contract in one file
`@master/ui/theme.json`	Every token of the theme with its value
`@master/ui/standalone.css`	The theme and every component compiled to plain CSS
`@master/ui/base.css`	The small reset the components assume
`@master/ui/behaviors`, `@master/ui/behaviors/<name>.js`	Every behavior with `attach()`, or one behavior, with types for TypeScript
`@master/ui/check`	The contract checker as a module

The compiled files are also reachable under @master/ui/dist/, which is the path a CDN serves: dist/standalone.css, dist/base.css, dist/themes/<name>.css, dist/contracts.json and dist/theme.json.

#Private

What	Example	Use instead
An internal component property that its contract does not list	`--btn-lift`, which the button uses to pass its travel between its own rules	A listed property, or a theme token: `--lift`
The structure of a selector	How a rule nests, which pseudo-element draws a mark, how specific a rule is inside the `components` layer	The class and the state mark; a utility on the element wins over any component rule
The values of the default theme	The shadow lists behind `--shadow-raised`, the stops of a gradient in `--surface-sheet`	The token or mixin name, redefined in a theme of your own
The order of declarations and of rules in a stylesheet	Which of two rules comes later	Nothing depends on it from outside the file
`behaviors/internal.js`	The helpers the combobox, command, listbox and menu behaviors share. Its own header says it is not a behavior	The behavior's function; or own the behavior and keep a copy of the file beside it
Files under `dist/` that this page does not name	Any other file a build leaves there	The paths in the table above
The files under `frameworks/`	The React, Svelte and Vue components as the package holds them. They are source to copy, not modules to import, and their props may change between releases	`npx master-ui add <name>`, which copies one; the copy is yours and does not change with a release

Implementation details can change while the contract stays the same. For example, a shadow can be retuned or a mark can move to another pseudo-element without changing the markup a component accepts. The result can still look different, so visual review remains part of an upgrade.

app.css

/* Public: the button contract lists --btn-height. */.checkout .btn {  --btn-height: 2.75rem;}/* Private: no contract lists --btn-lift, so a release may rename it. */.checkout .btn {  --btn-lift: 0px;}/* The public way to say the same thing is the theme token. */.checkout {  --lift: 0px;}

#What a change means

Change	Breaking
A public name is removed or renamed: a class, a required attribute, a state mark, a listed property, a token, a mixin, an export, a command, an import path	Yes
The default theme is retuned: a tone, a shadow, a gradient, a duration	No
Anything on the private list changes	No
A framework component in the package changes: a prop, its markup	No. A copy in a project stays as it was taken; `master-ui status` says that upstream moved

A visual retuning can preserve the contract. Decide which part the project needs to control: the installed release, one component's implementation or the theme's values.

Own the component. own copies its stylesheet, contract and behavior, when present. Wire the page to those copies to keep later package releases from replacing that implementation. The copied stylesheet still reads theme tokens, so owning it alone does not freeze its appearance. See customization.

npx master-ui own button

#Keep a local theme

Copy node_modules/@master/ui/theme.css into the project and import it after the library. Its token and mixin definitions take precedence over the package's definitions. This preserves the values you copied; new tokens and changes to how a component uses them can still affect the result. Theming describes how to maintain the file.

app.css

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

#While the package is experimental

Master UI is experimental: its versions are 0.x. Until 1.0 the tables above describe what a name is, not a promise to keep it. Any release may rename or remove a public name, and none comes with a deprecation period, a compatibility layer or a migration guide. The release notes list what changed.

So install an exact version and upgrade on purpose:

npm install @master/ui --save-exact

--save-exact records the selected version rather than a permitted version range. Commit the package manifest and lockfile together so other checkouts install the same dependency set. A local theme or component copy can then be reviewed against a known release.

For the components a project owns, the command line tool reports what moved. status compares each owned component with the installed package and lists the files that changed upstream since they were taken:

npx master-ui status

It exits with code 2 when an owned component changed upstream, so a job that runs after an upgrade can report it. npx master-ui diff button shows the difference between the saved base and the installed package. After reviewing and merging it yourself, npx master-ui accept button advances the saved base; it does not merge or edit your working copy. Customization walks through the commands.

Merging an upstream change

Compare, merge, then record the new base. diff compares the saved base with the installed package, leaving your working copy out of that comparison. You merge the changes you want into the working copy. Afterwards, accept copies the installed upstream files into the saved base and updates the ownership record; it leaves your merged working copy untouched. The file marks in the diagram are schematic, not a particular release diff.

For each upgrade:

Read the release notes and update the exact dependency version and lockfile.
Run npx master-ui check against the project's markup to find classes, elements or attributes that no longer match its contracts.
Review status and diff for owned and added components; merge before accepting a new base.
Build the application and exercise affected controls, overlays and keyboard paths. Compare light and dark appearance, including any local theme.

The checker validates markup against contracts; it cannot establish that application behavior or the rendered result is unchanged.