Skip to main content

Utilities

NUI provides a small set of low-specificity utility classes for layout, spacing, typography, and visual styling.

Utilities are designed to:

  • speed up composition
  • reduce custom CSS
  • preserve token-driven theming
  • maintain low CSS specificity
  • remain framework-agnostic

All utilities consume values from the theme token system.

Usage​

<div className="nui-flex nui-items-center nui-gap-2 nui-p-4 nui-bg-surface nui-rounded-md">
  Content
</div>

Design Principles​

Token-driven​

Utilities never hardcode values. They always reference design tokens.

Example:

nui-p-4 → var(--nui-space-4)
nui-bg-surface → var(--nui-bg-surface)
nui-rounded-md → var(--nui-radius-md)

Low Specificity​

Utilities use single-class selectors only. This prevents override conflicts.

Not a Tailwind Replacement​

NUI utilities are intentionally minimal and focus on:

  • layout composition
  • spacing
  • typography
  • theme alignment

Utility Categories​

1. Display & Layout​

ClassDescription
.nui-blockdisplay:block
.nui-inline-blockdisplay:inline-block
.nui-hiddendisplay:none
.nui-flexdisplay:flex
.nui-inline-flexdisplay:inline-flex
.nui-griddisplay:grid
.nui-flex-rowflex-direction:row
.nui-flex-colflex-direction:column
.nui-flex-row-reverseflex-direction:row-reverse
.nui-flex-col-reverseflex-direction:column-reverse
.nui-flex-wrapflex-wrap:wrap
.nui-flex-nowrapflex-wrap:nowrap
.nui-items-startalign-items:flex-start
.nui-items-centeralign-items:center
.nui-items-endalign-items:flex-end
.nui-items-baselinealign-items:baseline
.nui-items-stretchalign-items:stretch
.nui-justify-startjustify-content:flex-start
.nui-justify-centerjustify-content:center
.nui-justify-endjustify-content:flex-end
.nui-justify-betweenjustify-content:space-between
.nui-justify-aroundjustify-content:space-around
.nui-flex-1flex:1 1 0%
.nui-flex-autoflex:1 1 auto
.nui-flex-noneflex:none
.nui-growflex-grow:1
.nui-shrink-0flex-shrink:0

2. Positioning & Z-Index​

ClassDescription
.nui-relativeposition:relative
.nui-absoluteposition:absolute
.nui-fixedposition:fixed
.nui-inset-0inset:0
.nui-top-0top:0
.nui-right-0right:0
.nui-bottom-0bottom:0
.nui-left-0left:0
.nui-translate-x-halftransform:translateX(-50%)
.nui-translate-y-halftransform:translateY(-50%)
.nui-center-absoluteabsolute center
.nui-z-dockeddocked z-index
.nui-z-dropdowndropdown z-index
.nui-z-modalmodal z-index

3. Sizing​

ClassDescription
.nui-w-fullwidth:100%
.nui-w-screenwidth:100vw
.nui-w-autowidth:auto
.nui-w-64width:16rem
.nui-w-80width:20rem
.nui-h-fullheight:100%
.nui-h-screenheight:100vh
.nui-h-autoheight:auto
.nui-max-w-smmax-width:24rem
.nui-max-w-mdmax-width:28rem
.nui-max-w-lgmax-width:32rem
.nui-max-w-xlmax-width:36rem
.nui-max-w-fullmax-width:100%

4. Spacing​

ClassDescription
.nui-p-0padding:0
.nui-p-1padding:space-1
.nui-p-2padding:space-2
.nui-p-3padding:space-3
.nui-p-4padding:space-4
.nui-p-5padding:space-5
.nui-p-6padding:space-6
.nui-p-8padding:space-8
.nui-px-2padding-x space-2
.nui-px-4padding-x space-4
.nui-px-6padding-x space-6
.nui-px-8padding-x space-8
.nui-py-2padding-y space-2
.nui-py-4padding-y space-4
.nui-py-6padding-y space-6
.nui-py-8padding-y space-8
.nui-pt-2padding-top space-2
.nui-pt-4padding-top space-4
.nui-pb-2padding-bottom space-2
.nui-pb-4padding-bottom space-4
.nui-pl-4padding-left space-4
.nui-pr-4padding-right space-4
.nui-m-0margin:0
.nui-m-automargin:auto
.nui-mt-0margin-top:0
.nui-mt-1margin-top space-1
.nui-mt-2margin-top space-2
.nui-mt-4margin-top space-4
.nui-mt-6margin-top space-6
.nui-mt-8margin-top space-8
.nui-mb-1margin-bottom space-1
.nui-mb-2margin-bottom space-2
.nui-mb-4margin-bottom space-4
.nui-mb-6margin-bottom space-6
.nui-mb-8margin-bottom space-8
.nui-ml-2margin-left space-2
.nui-ml-4margin-left space-4
.nui-ml-automargin-left:auto
.nui-mr-2margin-right space-2
.nui-mr-4margin-right space-4
.nui-mx-automargin-x auto
.nui-mx-2margin-x space-2
.nui-mx-4margin-x space-4
.nui-my-2margin-y space-2
.nui-my-4margin-y space-4
.nui-gap-1gap space-1
.nui-gap-2gap space-2
.nui-gap-3gap space-3
.nui-gap-4gap space-4
.nui-gap-6gap space-6
.nui-gap-8gap space-8

5. Typography​

ClassDescription
.nui-text-xsfont-size xs
.nui-text-smfont-size sm
.nui-text-basefont-size base
.nui-text-lgfont-size lg
.nui-text-xlfont-size xl
.nui-font-normalfont-weight 400
.nui-font-mediumfont-weight medium
.nui-font-boldfont-weight bold
.nui-text-lefttext-align left
.nui-text-centertext-align center
.nui-text-righttext-align right
.nui-uppercaseuppercase
.nui-capitalizecapitalize
.nui-truncatetext truncate
.nui-no-underlineno underline
.nui-underlineunderline
.nui-line-throughline-through
.nui-italicitalic
.nui-not-italicnormal style
.nui-whitespace-nowrapnowrap
.nui-whitespace-pre-wrappre-wrap

6. Visuals​

ClassDescription
.nui-bg-pagebackground page
.nui-bg-surfacebackground surface
.nui-bg-subtlebackground subtle
.nui-bg-transparenttransparent background
.nui-text-defaultdefault text color
.nui-text-subtlesubtle text color
.nui-text-inverseinverse text
.nui-text-primaryprimary text
.nui-text-dangerdanger text
.nui-borderborder
.nui-border-tborder-top
.nui-border-bborder-bottom
.nui-border-rborder-right
.nui-border-lborder-left
.nui-rounded-smradius sm
.nui-rounded-mdradius md
.nui-rounded-lgradius lg
.nui-rounded-fullradius full
.nui-rounded-noneradius none
.nui-overflow-hiddenoverflow hidden
.nui-overflow-autooverflow auto
.nui-overflow-y-autooverflow-y auto

7. Interactivity​

ClassDescription
.nui-hover:bg-subtlehover background subtle
.nui-hover:text-primaryhover text primary
.nui-cursor-pointerpointer cursor
.nui-cursor-defaultdefault cursor
.nui-cursor-not-alloweddisabled cursor
.nui-pointer-events-nonedisable pointer events
.nui-pointer-events-autoenable pointer events
.nui-select-nonedisable selection

8. Transitions & Animations​

ClassDescription
.nui-transition-alltransition all
.nui-transition-colorstransition colors
.nui-transition-opacitytransition opacity
.nui-transition-transformtransition transform
.nui-duration-75duration 75ms
.nui-duration-100duration 100ms
.nui-duration-150duration 150ms
.nui-duration-200duration 200ms
.nui-duration-300duration 300ms
.nui-duration-500duration 500ms
.nui-ease-linearlinear easing
.nui-ease-inease-in
.nui-ease-outease-out
.nui-ease-in-outease-in-out
.nui-animate-fade-infade animation
.nui-animate-slide-upslide-up animation
.nui-animate-zoom-inzoom-in animation
.nui-animate-spinspin animation
.nui-animate-pulsepulse animation

9. Accessibility​

ClassDescription
.nui-sr-onlyscreen reader only
.nui-outline-noneremove outline
.nui-focus-ringfocus ring

Notes​

All utilities consume theme tokens and automatically adapt to theme overrides.

Example: Card Composition​

<div className="nui-bg-surface nui-border nui-rounded-lg nui-p-6 nui-flex nui-flex-col nui-gap-2 nui-transition-all">
  <h3 className="nui-text-lg nui-font-bold nui-text-default">Title</h3>
  <p className="nui-text-subtle">Description</p>
</div>

Use utilities for:

  • layout composition
  • spacing
  • alignment
  • typography
  • quick visual tweaks

Avoid utilities for:

  • component logic styling
  • complex interactive states
  • component theming (use tokens instead)