Skip to main content

Tailwind CSS

Configure the Moraine Tailwind CSS plugin for Tailwind CSS v4, scanner paths, and custom utilities.

View as Markdown

The moraine/tailwind entry exports a Tailwind CSS plugin. It maps Moraine tokens to CSS variables and registers semantic z-index utilities, keyframe animations, parametric transform utilities, tone utilities, and data-* / aria-* state variants.

Tailwind CSS v4#

In an existing Solid/Vite project, install Moraine, Tailwind, and Tailwind’s Vite integration:

pnpm add moraine
pnpm add -D tailwindcss @tailwindcss/vite
vite.config.ts
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'
import solid from 'vite-plugin-solid'

export default defineConfig({
  plugins: [tailwindcss(), solid()],
})

Register Moraine with the @plugin directive and scan its published distribution files with @source:

src/index.css
@import 'tailwindcss';
@plugin 'moraine/tailwind';
@source '../node_modules/moraine/dist';

Import ./index.css in src/main.tsx and define the theme variables described below. Keep the import in the application entry so the stylesheet loads when a user opens any route directly. See Tailwind’s Vite integration guide for the build-tool setup.

The @source path directive#

Tailwind CSS v4 ignores node_modules during automatic source detection. The Moraine plugin registers utility rules and variants, but not component files as sources. Use @source even when the plugin is registered. See Tailwind’s source detection guide.

Scan the full moraine/dist directory, and note the following requirements:

  1. Path resolution: @source paths are filesystem paths relative to the stylesheet, not package imports. Point to the published dist folder (for example, '../node_modules/moraine/dist' for src/index.css).
  2. Monorepos and workspaces: If moraine is hoisted to a root node_modules directory in a pnpm or npm workspace, adjust the relative path to point to the repository root:
    @source '../../../node_modules/moraine/dist';

Tailwind discovers static classes by scanning files, whether or not a lazy route has loaded. Cover route directories with automatic source detection or explicit @source entries. If you disable automatic detection with source(none), also register your application sources. These paths are relative to the stylesheet; automatic detection uses the working directory unless you configure a base path.

Theme variables#

Theme variables and page background and text styles belong in your CSS. The plugin registers utilities and variants but does not emit theme color values. You can reuse compatible variables from a shadcn/ui theme, but you must add Moraine’s independent --control surface in both themes and define its semantic shadows:

:root {
  --control: rgb(255, 255, 255);
  --shadow-surface: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
  --shadow-overlay: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
  --shadow-input: 0 1px 2px 0 rgb(0 0 0 / 0.05);
}
.dark {
  --control: rgb(23, 23, 23);
}

Set the global --sidebar-width in :root to customize the desktop sidebar width. Sidebar uses clamp(14rem, 25%, 20rem) when it is unset.

bg-control supplies outline field, unchecked choice, and upload surfaces. border-input keeps the existing boundary role, including neutral tracks and separators elsewhere. control uses the existing field text colors and has no dedicated foreground or state family. Alpha utilities such as bg-control/30 remain supported. See the form surface migration.

Surface hover and active utilities (hover:bg-accent-hover, active:bg-accent-active) mix the surface toward its foreground in browsers that support color-mix(in oklch, …), and fall back to the base surface color elsewhere. Tone components handle interaction states through the component tone channel. Tones also expose derived --<tone>-ink text colors and --<tone>-soft washes that mix toward transparent, so they composite on the local surface.

bg-backdrop reads --backdrop with a black-at-32% fallback. Component shadows use shadow-surface, shadow-overlay, and shadow-input, which read --shadow-surface, --shadow-overlay, and --shadow-input. Define these role tokens in :root, override them in .dark, and use none to remove a role’s shadow. Native size utilities such as shadow-xs use Tailwind’s own theme and stay independently configurable. See Backdrop and Semantic Shadows.

Injected utilities and variants#

The plugin registers the following utilities and variants with Tailwind v4:

Parametric transform utilities#

Combine these with animate-mo-enter and animate-mo-exit to customize motion:

  • Opacity: enter-opacity-<percent>, exit-opacity-<percent>
  • Scale: enter-scale-<percent>, exit-scale-<percent>
  • Translate: enter-translate-x-<num>, enter-translate-y-<num>, exit-translate-x-<num>, exit-translate-y-<num>
  • Rotate: enter-rotate-<deg>, exit-rotate-<deg>

See the Animations guide for details and interactive specimens.

Semantic z-index utilities#

  • z-base (1)
  • z-raised (2)
  • z-control (3)
  • z-sticky (10)
  • z-resize (20)
  • z-overlay (40)
  • z-floating (50)

Tone and accent utilities#

  • tone-<color> publishes a color group’s channels (--mo-tone, --mo-tone-foreground, --mo-tone-hover, and so on) on an element. Descendants read them with bg-tone, text-tone-ink, hover:bg-tone-hover, and similar utilities.
  • accent-scope and accent-fg-<color> let a host publish --mo-accent-fg (usually under hover: or focus-within:) so descendants switch to the accent foreground. Without it, accent-fg-<color> falls back to the named color.

State attribute variants#

Target component DOM states with these utility prefixes:

  • Data attributes: A fixed set of component state names, including data-active:, data-checked:, data-closed:, data-disabled:, data-expanded:, data-focused:, data-hidden:, data-highlighted:, data-invalid:, data-loading:, data-open:, data-pressed:, data-selected:, and data-submitting:.
  • ARIA attributes: aria-busy:, aria-checked:, aria-disabled:, aria-expanded:, aria-hidden:, aria-invalid:, aria-modal:, aria-pressed:, aria-readonly:, aria-required:, aria-selected:
<button class="bg-muted text-muted-foreground data-active:bg-primary data-active:text-primary-foreground">
  Filter
</button>

Design tokens and CSS variables#

The plugin maps utility classes such as bg-primary, text-foreground, and rounded-lg to CSS variables. Define your color palette and dimensions in your application stylesheet as described in the Design guide.

The default text-xs through text-9xl scale reads the local --font-size, and named radius utilities read --radius. Explicit Tailwind theme values can replace these mappings. See Typography and spacing for the differences between Tailwind, UnoCSS Wind3, and UnoCSS Wind4.

Troubleshooting#

Check the installation button on a clean dev-server start, after a restart with Vite’s cache retained, on a directly opened lazy-loaded route, and in a production preview.

  • No utility styles: Confirm Tailwind’s build integration runs and your application entry imports its stylesheet.
  • Application classes work, but Moraine classes are missing: Confirm @plugin 'moraine/tailwind' is loaded and @source points to the installed distribution. Registering a plugin does not scan a dependency.
  • Rules exist, but colors, radius, or shadows are missing: Check the referenced CSS variables and their scope. Unlike presetMoraine() with default options, the Tailwind plugin does not emit a complete default theme. Neither MoraineProvider nor the optional moraine/icon.css replaces theme variables or scanning.
  • Classes from a lazy route are missing: Check source coverage and keep the stylesheet import in the application entry. Correctly registered sources do not require navigating through the home page first.
  • Dynamically constructed classes are missing: Use complete static class maps. Tailwind cannot infer classes such as bg-${color}. In v4, include extra classes explicitly with @source inline() on versions that support it. The legacy JavaScript safelist option is not supported in v4. See Tailwind’s safelisting guide.

If clearing Vite’s dependency cache changes the symptom, recheck the imported stylesheet, registered sources, and theme configuration, then verify a restart with the cache retained. Clearing the cache does not replace @source and is not part of normal setup.