Upgrading to 0.4.0

One idea runs through this release: nothing the library puts into your stylesheet answers to a generic name any more. 1145 classes and 144 custom properties gained an nvb- prefix.

The rename is mechanical, but it is not cosmetic. Sharing names with a host application broke real applications in ways that were hard to trace back, and the two bugs fixed alongside it were both symptoms of the same idea being applied too loosely.

What changed

Before	After
.field, .field__label	.nvb-field, .nvb-field__label
.box, .panel, .row, .column	.nvb-box, .nvb-panel, .nvb-row, .nvb-column
.dropdown, .input-wrapper, .select-container	.nvb-dropdown, .nvb-input-wrapper, .nvb-select-container
.preview-form-body, .page__header	.nvb-preview-form-body, .nvb-page__header
--color-primary-500, --color-neutral-300	--nvb-color-primary-500, --nvb-color-neutral-300
--radius-md, --space-3, --text-body1	--nvb-radius-md, --nvb-space-3, --nvb-text-body1

Names that were never ours are untouched, so cdk-*, ng-*, cm-* and material-symbols-outlined stay exactly as they were.

Why the custom properties mattered most

The class rename fixes an ordinary collision: a host rule such as .field { border: 2px solid } used to land on our fields, because our .field set no border of its own and nothing was there to compete.

The token rename fixes something less obvious. A design system that feeds Tailwind stores its palette as HSL channel triplets:

:root {
  --color-neutral-300: 214 32% 91%;
}

We declared the same name as an oklch color on .nvb-root, and inside a view ours won. Any host rule that still applied there, a global input style for instance, then resolved to hsl(oklch(86.94% 0.0199 253.37) / 1). That is not a color, so the whole declaration fell back to currentColor, and inputs appeared with thick black borders that matched the text. Nothing in the browser pointed at the palette.

Both palettes now coexist, because they no longer share a single name.

Fixing your integration

Search your own code for the old names. Most projects have only a handful of hits, usually in one place.

grep -rnE "\.(field|box|panel|row|column|dropdown|page|view|preview-[a-z-]+)\b" src
grep -rn -- "--color-\|--radius-\|--space-\|--text-" src

Four places tend to have them:

Host stylesheets and directives that reach into a rendered view. Add the prefix.

Saved views, in settings.customCss. These live in your database rather than your repository, so they are the easiest to forget. There is no automatic migration, because rewriting CSS a creator wrote is not something a migration should do quietly.

Theme variables passed through api.setCssVariables(), setCustomTheme() or runtimeSettings. Keys have to match the new names or the override does nothing.

Custom element and template CSS that reads tokens, such as var(--color-neutral-300).

If you have to support both versions for a while, list both spellings side by side. A selector list costs nothing and lets the change land before the package bump:

.nvb-page__header,
.page__header {
  display: none;
}

Two fixes worth knowing about

Floating panels no longer open in the wrong place. Menus use position: fixed and were positioned from viewport coordinates, which the browser resolves against the nearest ancestor that establishes a containing block. Host applications create one routinely with transform, filter or will-change, and the menu then landed off by the whole scroll offset. On a long form that is hundreds of pixels, far enough to look as though clicking did nothing at all. Select, multi select, autocomplete, phone country, datepicker, date range, time picker and label tooltips now resolve their real containing block first.

Views stay readable on a dark page. .nvb-root now paints its own surface and declares its color scheme rather than borrowing whatever the host uses. Previously the near black labels disappeared into a dark background while the inputs kept their own white fill and looked correct, which read as the labels being missing. Set --nvb-surface: transparent where a view already sits on a surface you control.

See Theming for the token families and Layer order if your application uses cascade layers.