# NuvoUI

> NuvoUI core (`@nuvoui/core`) is a human-readable, utility-first SCSS framework and the foundation layer of the NuvoUI design system. Version 2.0.1 provides design tokens emitted as `--nu-*` CSS custom properties, light and dark themes, utility classes, and SCSS mixins through `@include apply(...)`. It ships SCSS and CSS only: no JavaScript, no runtime and no CLI.

Install: `npm install -D sass @nuvoui/core` (Dart Sass 1.79 or later, below 2.0).

Configure once, in the first `@use`:

```scss
@use "@nuvoui/core" as * with (
  $brand: #4361ee,
  $generate-utility-classes: true
);
```

Rules that are easy to get wrong:

- Inside `apply()`, modifiers come after the utility, state first and breakpoint last: `@include apply(bg(gray, 100) hover lg)`. Never `hover:bg(...)` or `lg:p(4)`.
- Responsive classes use an `@` suffix: `p-4@md`, `flex@md`, `hide@md`. Colour classes have no responsive variants: use `@include apply(bg(red) lg)`. State classes use a prefix: `hover:bg-brand`. There is no `lg:` syntax.
- Flex modifiers sit on the `.flex` element itself: `class="flex between x-center"`, never `between` alone. Flex child classes such as `grow` and `fill-6` need a `.flex` parent and work only on its direct children.
- Names are human-readable: `between` and `x-center`, not `justify-between` and `items-center`. Do not invent classes or mixins.
- A unitless number in a scale mixin is a configuration key: `p(4)` is `var(--nu-space-4)`. Write a unit for a custom value: `p(1.5rem)`.
- A role's resting fill is the bare token: `--nu-brand`, `token(brand)`, `bg(brand)`. There is no `-default` suffix.
- Use theme tokens for themed UI (`bg(surface)`, `text-color(muted)`) rather than hex values or palette shades, so styles follow light and dark themes.
- Unknown keys and values fail at compile time with an error that names the valid options.
- Utility classes are emitted only with `$generate-utility-classes: true`. Tokens and base styles are emitted either way.
- Configuration, `apply()` and every mixin need a Sass compile step (Dart Sass, run by your bundler or the `sass` CLI). The package also ships a prebuilt `dist/nuvoui.min.css` with the default configuration. There is no runtime in the browser.
- Logical utilities (`ps-4`, `ms-4`, `text-start`) are added alongside the physical ones (`pl-4`, `ml-4`, `text-left`), which remain. Use the logical forms for layouts that must flip in right-to-left pages.

The complete documentation text is in [llms-full.txt](https://nuvoui.io/llms-full.txt).

## Getting started

- [Introduction](https://nuvoui.io/core/): NuvoUI core is a human-readable, utility-first SCSS framework and the foundation layer of the NuvoUI design system.
- [apply()](https://nuvoui.io/core/getting-started/apply/): Use NuvoUI utilities as SCSS mixins in one call, with state and breakpoint modifiers, custom values, and both the global and the namespaced way of loading core.

## Foundations

- [Configuration](https://nuvoui.io/core/foundations/configuration/): Configure NuvoUI core once with Sass with(), choose what it emits with $generate-utility-classes and feature flags, scope it with $parent-selector, and replace its scale maps.
- [Theming](https://nuvoui.io/core/foundations/theming/): Light and dark themes with data-theme, the operating system fallback, inverse sections, high contrast, theme override maps with the name stop syntax, and a different brand colour per theme.
- [Tokens](https://nuvoui.io/core/foundations/tokens/): How NuvoUI design tokens are organised, named and read in SCSS, with the full list of --nu-* custom properties generated from the compiled core build.

## Layout

- [Container](https://nuvoui.io/core/layout/container/): A centred page container whose maximum width steps up at each breakpoint, with flex and grid variants, and query container classes for container queries.
- [Flex](https://nuvoui.io/core/layout/flex/): Flexbox layout with readable names for direction, main axis and cross axis alignment, wrapping, gap, a 12-column fill system and equal-share rows with stretch.
- [Grid](https://nuvoui.io/core/layout/grid/): CSS grid layout with equal columns and rows, auto-fit and auto-fill tracks, flow control, grid-only item alignment, spans and placement mixins.

## Utilities

- [Alignment](https://nuvoui.io/core/utilities/alignment/): Vertical alignment utilities for inline content and table cells, with responsive variants and mixins of the same name.
- [Animations](https://nuvoui.io/core/utilities/animations/): Ready-made pulse, spin, ping, fade and shake animation classes, configurable animation mixins that emit their keyframes once, and reduced motion handling.
- [Backdrop filters](https://nuvoui.io/core/utilities/backdrop-filters/): Backdrop filter utilities that blur, dim and recolour whatever sits behind an element, composed from --nu-backdrop-* properties on a backdrop-layer, plus ready-made glass presets.
- [Borders](https://nuvoui.io/core/utilities/borders/): Border width, colour, style and radius utilities built on the --nu-border-width-* and --nu-radius-* tokens, with logical sides and corners for right-to-left layouts.
- [Colours](https://nuvoui.io/core/utilities/colours/): Background, text and border colour utilities for semantic roles, hue roles, palette shades 50 to 950, theme surfaces and basic colours, all emitted as --nu-* tokens that follow the theme.
- [Cursor](https://nuvoui.io/core/utilities/cursor/): Cursor utilities that set the mouse pointer shown over an element.
- [Display](https://nuvoui.io/core/utilities/display/): Display, visibility, overflow and text truncation utilities, with responsive hide and show classes and a screen reader only helper.
- [Helpers](https://nuvoui.io/core/utilities/helpers/): The sr-only class for content that only screen readers announce, and the optional breakpoint debugger overlay, with the setting that controls each.
- [Opacity](https://nuvoui.io/core/utilities/opacity/): Opacity utilities built on their own $opacities scale and the --nu-opacity-* tokens, with hover, focus, active, group-hover and responsive variants.
- [Position](https://nuvoui.io/core/utilities/position/): Position type, offset and inset utilities, with logical start and end offsets for right-to-left layouts, percentage offsets and absolute centring.
- [Shadows](https://nuvoui.io/core/utilities/shadows/): Box shadow utilities built on the --nu-shadow-* tokens, with darker colour variants, inset shadows, elevation levels, state and responsive variants.
- [Sizing](https://nuvoui.io/core/utilities/sizing/): Width, height, minimum and maximum size utilities built on the spacing scale, with percentages, breakpoint widths and sizing keywords.
- [Spacing](https://nuvoui.io/core/utilities/spacing/): Padding, margin, gap and child spacing utilities built on the --nu-space-* token scale, with logical properties for right-to-left layouts.
- [Transforms](https://nuvoui.io/core/utilities/transforms/): Translate, scale, rotate and skew utilities that combine on one element through registered --nu-* transform properties, plus transform origin classes.
- [Transitions](https://nuvoui.io/core/utilities/transitions/): Transition utilities with a default duration and easing, property variants, and duration, easing and delay classes built on the --nu-duration-* and --nu-ease-* tokens.
- [Typography](https://nuvoui.io/core/utilities/typography/): Font size, weight, line height, letter spacing, alignment, case, decoration, wrapping and font family utilities built on the --nu-font-* and --nu-line-height-* tokens.
- [Z-index](https://nuvoui.io/core/utilities/z-index/): Stacking utilities with named layer levels emitted as --nu-z-* tokens, plus numbered keys for local ordering.

## Components

- [Tooltips](https://nuvoui.io/core/components/tooltips/): CSS-only tooltips set with the data-tooltip attribute, with eight positions, three wrapping widths and --nu-tooltip--* component variables.

## Tools

- [Container queries](https://nuvoui.io/core/tools/container-queries/): Query container classes and the container-up, container-down, container-between, container-only and container-query mixins, which style an element by the width of its container.
- [Media queries](https://nuvoui.io/core/tools/media-queries/): The media-up, media-down, media-between and media-only mixins, built on the $breakpoints map, with a 0.02px offset on upper bounds so ranges never overlap.

## Reference

- [A to Z index](https://nuvoui.io/core/reference/a-z/): Every public NuvoUI core mixin and function in alphabetical order, generated from the SCSS doc blocks, with links to the full reference.
- [Functions](https://nuvoui.io/core/reference/functions/): Every public NuvoUI core function, generated from the SCSS doc blocks: parameters, return values and compiled examples.
- [Layout mixins](https://nuvoui.io/core/reference/layout-mixins/): Every public flex, grid and container mixin of NuvoUI core, generated from the SCSS doc blocks with parameters and compiled examples.
- [Tool and theme mixins](https://nuvoui.io/core/reference/tool-and-theme-mixins/): Public NuvoUI core mixins for apply(), media and container queries, user preferences, feature support, themes and tooltips, generated from the SCSS doc blocks.
- [Utility mixins](https://nuvoui.io/core/reference/utility-mixins/): Every public utility mixin of NuvoUI core, generated from the SCSS doc blocks with parameters and compiled examples.

## Playground

- [NuvoUI Playground](https://nuvoui.io/playground/): Write SCSS with NuvoUI core and see the compiled CSS and a live preview; Dart Sass runs in the browser.

## Optional

- [NuvoUI comparisons](https://nuvoui.io/vs/): Overview of how NuvoUI core compares with other tools.
- [NuvoUI vs Tailwind CSS](https://nuvoui.io/vs/tailwind/): Syntax, custom values, theming, RTL, tokens and build approach, with sources.
- [NuvoUI vs Bootstrap](https://nuvoui.io/vs/bootstrap/): Components, syntax, customisation, colour modes, RTL and tokens, with sources.
- [NuvoUI vs Ant Design](https://nuvoui.io/vs/ant-design/): A CSS foundation layer compared with a React component library, with sources.