UnoCSS
Configure the UnoCSS preset, file scanning, Wind3 and Wind4 compatibility, and semantic color variable generation.
presetMoraine(), exported from moraine/unocss, integrates Moraine with UnoCSS. It maps semantic colors, border radiuses, shadows, animation keyframes, z-index utilities, and state variants into UnoCSS.
Installation and config#
In an existing Solid/Vite project, install Moraine and the UnoCSS integration:
Add presetMoraine() alongside your Wind preset (presetWind4 or presetWind3). The preset targets Wind4 by default; set wind3: true for Wind3. It does not detect which Wind preset is installed. Scan your application files and Moraine’s published classes explicitly:
Solid and Vite integration#
Place unocss.config.ts and vite.config.ts in the application root. Register the UnoCSS plugin before Solid’s plugin:
Import the generated CSS once in the application entry so every route has it:
The HTML entry must have a matching mount element and load src/main.tsx:
Use the App from the installation example to check the button’s appearance. The preset’s default theme does not need MoraineProvider. With TypeScript, add vite/client to your compiler types so the virtual CSS import resolves.
Scanning component classes#
The glob ./node_modules/moraine/dist/**/*.{mjs,jsx} scans the whole moraine/dist directory. The preset does not configure scanning paths for your application.
Filesystem scanning reads these classes regardless of which modules Vite has requested. Keep both the application and package globs, including lazy-loaded route files and .ts files that contain class maps. In @subf/unocss/vite, the pipeline.include filter also applies to filesystem extraction, and UnoCSS’s default filter omits .mjs and .ts. Changing this filter replaces the default, so keep every extension your app uses. See UnoCSS’s extraction guide.
Filesystem globs are relative to Vite’s root, and the examples assume src/ and node_modules/moraine live under that root. Adjust the globs if you set a different Vite root, keep routes outside src/, or use a workspace with Moraine installed at the repository root. Add your Markdown or MDX directories when they contain application classes.
Verification and troubleshooting#
Verify the button from the installation guide on a clean dev-server start, after a restart with Vite’s dependency cache retained, on a directly opened lazy-loaded route, and in a production preview. Check its background, padding, and border radius. A working click handler does not verify CSS generation.
If styles are missing:
- Confirm
virtual:uno.cssis imported in the application entry and the UnoCSS plugin runs before the Solid plugin. - Confirm both the Wind preset and
presetMoraine()are enabled. With Wind3, passwind3: true. - Check that the filesystem globs match the installed Moraine distribution and every application source directory, including lazy routes.
- Check that
pipeline.includeallows those file extensions and that no custom exclusion filter rejects the files. - Inspect a missing class in browser DevTools. A missing CSS rule points to extraction or utility configuration. An existing rule with an unresolved
--primaryor another theme variable points to theme configuration. WiththemeDefaults: false, the application must provide its theme variables.
For a suspected dependency-cache issue, stop the server and run your Vite dev command with --force (for a dev script that runs Vite, pnpm run dev --force). Alternatively, remove Vite’s cacheDir, which defaults to node_modules/.vite, before restarting. While diagnosing cached dependency requests, temporarily disable browser caching. See Vite’s dependency caching guide.
After you correct the scan configuration, restart again with the cache retained. Clearing the cache is a diagnostic step, not part of normal startup. An improvement after --force alone does not establish a Moraine runtime bug. Restart after upgrading Moraine so UnoCSS scans its published files again.
With lazy routes, keep the CSS import in the application entry; do not rely on visiting another route to load styles. Filesystem scanning discovers static classes before the route loads, but neither it nor pipeline extraction can infer runtime strings such as bg-${color}. Use complete static class maps or an explicit UnoCSS safelist for application-generated classes.
Preset options#
presetMoraine() provides Moraine’s utility tokens, state variants, opaque neutral light and dark colors as RGB values, a translucent backdrop, default shadows, and base values for radius, font size, and spacing. Dark border and input use rgb(35, 35, 35) and rgb(47, 47, 47), and their colors stay the same across parent surfaces. The status colors info, success, warning, and danger follow Moraine’s tuned status palette. The default selectors are :root and .dark. Configure single-value tokens at the top level, and put colors, shadows, and colorScheme in named override entries.
The default semantic shadows use the Tailwind values inherited by the shadcn/ui neutral theme: surface → sm, overlay → md, input → xs. The preset emits --shadow-surface, --shadow-overlay, and --shadow-input at :root. Dark mode inherits these values unless override.dark.shadows replaces them. Native size utilities such as shadow-xs keep the CSS engine’s own values and configuration. Set themeDefaults: false to omit the default colors and semantic shadows while keeping explicit overrides.
| Option | Default | Behavior |
|---|---|---|
wind3 |
false |
Enables Wind3 theme mappings and semantic color alpha compatibility. Native numeric spacing and sizes remain unchanged. |
themeDefaults |
true |
Emits neutral light/dark colors and color schemes, default shadows, and HTML background/text styles. Set false when your CSS defines the theme. |
override |
omitted | Overrides the built-in neutral light and dark colors or adds named themes. |
override.<name>.colorScheme |
light for the built-in light theme; dark for dark; omitted for custom themes |
Accepts light or dark only. Emits color-scheme on the theme selector; explicit values still apply with themeDefaults: false. |
mix |
{ hover: 6, active: 10, ink: 25, soft: 12, border: 20 } |
Sets the color-mix percentages for hover, active, ink, soft, and border states. A number from 0 to 100 becomes a percentage; a string is used as written. Each configured value is written as a --mo-mix-* variable. Overridable per theme via override.<name>.mix. |
radius |
0.625rem |
Base radius written to --radius at :root; override per theme when needed. |
fontSize |
1rem |
Base font size written to --font-size at :root; used by Wind4 typography rules. |
spacing |
0.25rem |
Base spacing unit written to --spacing at :root. |
sidebarWidth |
omitted | Writes an explicit global --sidebar-width at :root; overridable per theme. Sidebar supplies its own fallback when unset. |
Theme tokens#
For grouped colors such as primary and muted, a string is shorthand for { base: value }. Expand a tone to override foreground or ink without repeating base. Single-value colors (foreground, border, input, control, backdrop, and ring) accept CSS strings only. control sets field fills independently of boundaries and parent surfaces. Color names and fields match Moraine’s semantic colors. Colors and shadows belong inside named override entries. shadows supports only surface, overlay, and input, which emit --shadow-surface, --shadow-overlay, and --shadow-input; see Backdrop and Semantic Shadows. The single values radius, fontSize, spacing, and sidebarWidth are also accepted inside an override entry. Configure font families in CSS through --font-sans, --font-mono, and --font-serif; see Typography and Spacing. Put other custom properties in your CSS file.
light and dark default to :root and .dark. Any other name defaults to [data-theme="name"]; set selector on any entry to use a different CSS selector. The preset emits the default light colors first, then dark colors, then custom themes in configuration order. Light and dark overrides merge with their respective defaults. A partial custom theme inherits missing variables through the CSS cascade, including variables used by portaled overlays when they are declared on an ancestor of the portal.
The built-in light and dark themes emit color-scheme: light and color-scheme: dark, so native browser controls follow the theme. colorScheme has type 'light' | 'dark' and belongs inside override.<name>, not at the top level. Its declaration follows the entry’s selector, including custom selectors for light and dark. Custom themes inherit the CSS color scheme unless you configure one. themeDefaults: false omits the default color schemes while keeping explicit overrides. colorScheme writes the native CSS color-scheme property; it does not create a custom property.
See Moraine-specific Variables for the form surface, backdrop, shadow, interaction, typography, sidebar, and animation variables.
Semantic color alpha modifiers such as bg-primary/20 use color-mix(in srgb, …) in supported browsers. presetWind4 supports color-mix with a fallback. With wind3: true, Wind3 gains the same alpha syntax.
Wind3 compatibility#
Use presetMoraine({ wind3: true }) with presetWind3(). This enables Wind3’s semantic token mappings, color alpha compatibility, and the forced-colors: variant and forced-color-adjust-* utilities that Wind3 lacks. Numeric spacing and size utilities keep Wind3’s native values and explicit theme overrides, so changing --spacing does not scale them. Use explicit variable utilities such as p-(--app-padding) for runtime spacing changes.
With Wind3, configure font sizes through UnoCSS’s theme.fontSize, because --font-size does not scale typography. Customize named radiuses through theme.borderRadius. With Wind4, local --font-size and --radius values scale the default typography and radius tokens, and you customize them through theme.text and theme.radius. Explicit UnoCSS theme values take precedence in both modes. Use leading-* to set line height independently of font size.
Font families#
Configure font families through UnoCSS’s theme object, separately from the presetMoraine() options. Wind4 uses theme.font; Wind3 uses theme.fontFamily:
For Wind3, use presetWind3() with presetMoraine({ wind3: true }) and put the same family entries under theme.fontFamily. These explicit theme values take precedence over Moraine’s variable references. To keep runtime font switching, use values such as sans: 'var(--font-sans)' and define the corresponding CSS variables in your stylesheet. Load custom font files separately.
Surface states and tone derivation#
Moraine separates semantic roles into surfaces (background, card, popover, muted, accent) and tones (primary, secondary, neutral, danger, info, success, warning).
For surfaces, the internal --mo-<surface>-hover and --mo-<surface>-active variables mix the surface base color toward its foreground, inside an @supports (color: color-mix(in oklch, black, white)) block, using the configured mix percentages. The hover:bg-<surface>-hover and active:bg-<surface>-active utilities read an explicit --<surface>-hover or --<surface>-active first, then these mixed values, then the base color:
For tones, semantic utilities (such as hover:bg-primary-hover, active:bg-primary-active, and bg-primary-soft) resolve through a three-tier fallback chain:
- Explicit theme override (
colors.<tone>.hover,active,ink,soft, orborder), which emits--<tone>-hover,--<tone>-active,--<tone>-ink,--<tone>-soft, or--<tone>-border. - Auto-mixed state, emitted as internal
--mo-<tone>-*variables inside an@supports (color: color-mix(in oklch, ...))block, using the configuredmix.hover,mix.active,mix.ink,mix.soft, ormix.borderpercentage. Soft blends withtransparentso the wash composites on the local surface. Border blends withvar(--border)for an opaque, subtle boundary. - Base fallback:
var(--<tone>)for hover, active, and ink;transparentfor soft;var(--border)for border.
Moraine’s own component recipes (such as Button and Badge) bind to the universal --mo-tone channel (bg-tone, border-tone, border-tone-border, hover:bg-tone-hover, active:bg-tone-active, bg-tone-soft, hover:bg-tone-soft-hover, and active:bg-tone-soft-active), which avoids compound variants for every tone. The tone-<color> utility publishes a color group’s channels on any element. Application classes, application components, and theme overrides can use the tone tokens and utilities directly.
When your CSS supplies its own palette, disable the built-in palette and add Moraine’s --control variable:
Define your :root and .dark color variables, including an explicit control surface:
themeDefaults: false omits control values unless you configure them in override. A shadcn/ui palette alone is not sufficient; see the form surface migration. control has no foreground or state family, uses the existing field foreground, and supports explicit utility opacity such as bg-control/30. With themeDefaults: false, the preset still emits the default --radius, --font-size, and --spacing values, which your CSS can override.