About NebulaKit

Make it your only UI framework

NebulaKit is not just a library with a couple of components, it is a framework that acts as a complete system for the UI of your app. It takes care of the whole page: NebkitProvider sets the global defaults, and the library styles html and body, locks the page scroll and layers its portals and overlays above the page.

It is not tested alongside other UI frameworks, so importing a few of its components into an existing app built with another one is not recommended. Adopt it for the whole app instead.

Wrap the whole app

<NebkitProvider>  <App /></NebkitProvider>

Stay within the system

NebulaKit is opinionated and works as a system. Spacing, sizes, colors, radii and the way the parts of a component fit together are decisions already made and wired in internally. Those internals aren't meant to be overridden.

The flexibility lives in the props. Scales, tones, variants, responsive values and the global settings on NebkitProvider already cover what you need to adapt a component, so when you want it to look different, reach for a prop first.

For real edge cases every component takes elemAttrs, which passes attributes, style included, straight to the underlying element. Treat it as a last resort, not as a way to customize. It goes around the system, so the result is unpredictable: an override can clash with values the component manages itself, hold in one state and not in another, or stop working when the internals change in a later version.

Avoid

<Button elemAttrs={{ style: { paddingInline: '8px', borderRadius: 0 } }}>Save</Button>

Prefer

<Button scale="sm" radius="0px">Save</Button>

Tint large interactive surfaces

Filled surfaces are opaque. They suit small, self-contained elements where the element itself is the content, like buttons, chips or nav items. Anything stacked on a filled surface paints its own color over it, so when a large filled area reacts to hover or press, the elements inside it, like a divider, keep their color and stand out from the changing background.

Tinted surfaces are see-through, so whatever is drawn on them shows the surface through itself and follows its hover, press and contrast on its own. Use them for large areas that hold content, especially interactive ones. That is why Card comes in tinted variants only, and a raw Box acting as one should use bgMode="tinted" too.