Installation

WovenUI core is one npm package, @wovenui/core. It ships the SCSS source and a prebuilt stylesheet, so you can link a CSS file or compile core with your own configuration.

Requirements

• Dart Sass >=1.79.0 <2. It is a peer dependency: install the sass package next to core. Only needed to compile SCSS; the prebuilt CSS needs nothing.
• Node.js with npm or pnpm.

Install

npm install -D sass @wovenui/core

With pnpm: pnpm add -D sass @wovenui/core.

Two ways to use it

Prebuilt CSS

The package ships a compiled stylesheet with every utility class and the default configuration. Link it and use the classes.

<link rel="stylesheet" href="node_modules/@wovenui/core/dist/wovenui.min.css">

What the prebuilt stylesheet gives with no Sass: a card built from classes only

Card title

Padding, surface, border, radius and shadow all come from classes in the linked file.

<article class="p-4 bg-surface border rounded-lg shadow-sm">
  <h3 class="text-lg font-semibold">Card title</h3>
  <p class="text-muted">Padding, surface, border, radius and shadow all come from classes in the linked file.</p>
</article>

No Sass is involved, so the brand color, the scales and the breakpoints are the defaults. To change them, use SCSS.

SCSS

@use "@wovenui/core" loads the full API: apply(), every mixin, token() and the configuration variables. Configure it once, with with(), in the first @use.

@use "@wovenui/core" as * with (
    $brand: #4361ee,
    $generate-utility-classes: true,
    $breakpoints: (
        "sm": 640px,
        "md": 768px,
        "lg": 1024px,
    )
);

.card {
    @include apply(p(4), bg(surface), rounded(md), shadow(md) hover, p(6) md);
}

The .card rule above, rendered with the site's configuration, not the with() values (hover it, pick a width past md)

PhoneTabletLaptopDesktopFull

SCSS

@use "@wovenui/core" as *;

.card {
  @include apply(p(4), bg(surface), rounded(md), shadow(md) hover, p(6) md);
}

HTML

<article class="card">
  <strong>Card title</strong>
  <p>Padding grows from the md breakpoint, and the shadow appears on hover.</p>
</article>

Compiled CSS

.card {
  padding: var(--wu-space-4);
  background-color: var(--wu-bg-surface);
  border-radius: var(--wu-radius-md);
}
.card:hover {
  box-shadow: var(--wu-shadow-md);
}
@media (min-width: 768px) {
  .card {
    padding: var(--wu-space-6);
  }
}

$generate-utility-classes is false in the SCSS entry. Set it to true to get the classes in your compiled CSS; leave it off when you style with apply() only.

Package entries

Every entry in the exports field of @wovenui/core:

Import	File	Output
@wovenui/core (Sass)	src/styles/index.scss	The API, plus tokens, reset, base styles, tooltips and @property registrations; utility classes with $generate-utility-classes: true
@wovenui/core (CSS)	dist/wovenui.min.css	Prebuilt CSS, every class, default configuration. Used by tools that resolve the style or default condition
@wovenui/core/scss	src/styles/index.scss	Same as the Sass main entry
@wovenui/core/mixins	src/styles/mixins/index.scss	The same API and with() configuration, no CSS
@wovenui/core/css	dist/wovenui.css	Prebuilt CSS, unminified
@wovenui/core/min.css	dist/wovenui.min.css	Prebuilt CSS, minified
@wovenui/core/sassdoc.json	dist/sassdoc.json	SassDoc data of every documented mixin, function and variable, for editor tooling

A Sass compiler resolves @use "@wovenui/core" through the sass condition, so it gets the SCSS source, not the CSS file.

The mixins entry

@wovenui/core/mixins has the same API as @wovenui/core and emits no CSS. Mixins used in a rule output their declarations, and animation mixins still add their keyframes. Use it in every file that compiles on its own: a CSS module, a Vue, Svelte or Astro <style> block. Loading the main entry there repeats the tokens and base styles in each compiled file. Load @wovenui/core once, in the global stylesheet. See Component styles.

@use "@wovenui/core/mixins" as * with ($brand: #4361ee);

.card {
    @include apply(p(4), bg(surface), rounded(md));
}

.card {
  padding: var(--wu-space-4);
  background-color: var(--wu-bg-surface);
  border-radius: var(--wu-radius-md);
}

What the entry emits

@use "@wovenui/core" emits CSS on its own, before any of your rules:

Output	When
@layer reset, components (reset, tooltips)	Always. Tooltips follow the tooltips flag alone, independent of $generate-utility-classes
@layer base (base element styles, .sr-only)	base feature flag on (default), independent of $generate-utility-classes
@property registrations (transform variables, --wu-gap, transition group variables)	Always, independent of feature flags
Tokens (fixed :root block, light, dark, inverse, dark fallback, high-contrast twins when set)	theme feature flag on (default), independent of $generate-utility-classes
Utility classes	$generate-utility-classes: true and the class’s feature flag on

Without the classes this is about 42 KB compressed. Every file that loads @wovenui/core emits it, so load the main entry once and use the mixins entry everywhere else.

Bundlers

Vite, Next.js (Turbopack and webpack) and Astro compile SCSS once sass is installed, and resolve @use "@wovenui/core" through the package exports with no extra configuration. Svelte also needs vitePreprocess() in svelte.config.js for <style lang="scss"> blocks.

The setup guides hold the files of apps that passed a production build:

• React with Vite
• Next.js
• Vue with Vite
• Svelte with Vite
• Astro
• Plain HTML

Without a bundler

The Sass command line does not read node_modules by default. Load core with the pkg: prefix and turn on the Node package importer.

src/styles/main.scss

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

npx sass --pkg-importer=node --style=compressed src/styles/main.scss dist/main.css

Add --watch to recompile on every save. Without --pkg-importer=node, Sass stops with Can't find stylesheet to import.

Configure once

Configuration happens in the first @use of the module. Every later @use gets the same configured module, so pass with() once, in one file, and load that file first. Configuring a module that is already loaded raises an error:

// error
@use "@wovenui/core";
@use "@wovenui/core" as woven with ($brand: #4361ee);

This module was already loaded, so it can't be configured using "with".

To share one configuration across files, forward it from a partial and load the partial everywhere. See Configuration for every variable.

Next

• Utility classes: the class syntax, breakpoints and states.
• apply(): the same utilities as SCSS mixins.
• Component styles: the mixins entry in CSS modules and component style blocks.