NibCSS

Debugging & the dev overlay

Turn on diagnostics, read them in the terminal and the browser overlay, and inspect generated CSS.

2 min readv1

Turn diagnostics on#

TypeScript
export default defineConfig({
  debug: true,
  language: "en",   // uz (default) · en · ru · tr · es · de · zh
});

In the terminal#

At build time every problem is printed like a compiler error — file, line, the source line, the message, what the shorthand means, values that would work and spelling suggestions:

Text
[nib] src/App.tsx:92:14
  <section nib="pos=red; ovf=hidden">
  Invalid value "red" for "position"
  pos is short for position — accepts static, relative, absolute, fixed, sticky

In the browser: the overlay#

With the Vite plugin in development, a small orb appears in a corner of the page:

  • an amber ring means warnings, red means something is broken, a badge counts them;
  • click it to open a panel listing each problem with its message, the shorthand's meaning, values that would have worked, "did you mean?" chips (click to copy) and the file:line link;
  • drag the orb or use arrow keys to move it to another corner; the panel has S / M / L sizes;
  • fixed problems disappear without a reload, and the orb turns green and leaves when none are left.

Disable it with nib({ devtools: false }).

Runtime diagnostics#

Dynamic attributes are checked in the browser and dispatched as events:

TypeScript
document.addEventListener("nib:warning", (e) => {
  console.warn("[nib]", (e as CustomEvent).detail);
});

What gets reported#

Text
Unknown utility "trf" — did you mean "t", "tf", "trn"?
Unknown token "$color.brnd" — did you mean "color.brand"?
Invalid value "red" for "opacity" — accepts 0.7, 0, .5, 10%, 75%
Unknown utility or component "btnn" — did you mean "btn"?
Unknown modifier "xz" — did you mean "xs", "xl", "sm"?
Circular component reference "card"
Conflicting breakpoints "lg" vs "md"

Each message is explained in the error catalog.

Inspecting generated CSS#

  • DevTools → Elements: select the element; each nib-… class is one rule (or one recipe).
  • Runtime: Nib.css() (CDN) or runtime.css() returns the full stylesheet.
  • Engine: createEngine(config).process("…") shows classes, rules and warnings for any string.
  • Admin playground of this site compiles any snippet and shows the CSS and warnings.

Next steps#