Tailwind CSS Development

Documentation

Use search-docs for detailed Tailwind CSS v4 patterns and documentation.

Basic Usage

• Use Tailwind CSS classes to style HTML. Check and follow existing Tailwind conventions in the project before introducing new patterns.
• Offer to extract repeated patterns into components that match the project's conventions (e.g., Blade, JSX, Vue).
• Consider class placement, order, priority, and defaults. Remove redundant classes, add classes to parent or child elements carefully to reduce repetition, and group elements logically.

Tailwind CSS v4 Specifics

• Always use Tailwind CSS v4 and avoid deprecated utilities.
• corePlugins is not supported in Tailwind v4.

CSS-First Configuration

In Tailwind v4, configuration is CSS-first using the @theme directive — no separate tailwind.config.js file is needed:

@theme {
  --color-brand: oklch(0.72 0.11 178);
}

Import Syntax

In Tailwind v4, import Tailwind with a regular CSS @import statement instead of the @tailwind directives used in v3:

- @tailwind base;
- @tailwind components;
- @tailwind utilities;
+ @import "tailwindcss";

Replaced Utilities

Tailwind v4 removed deprecated utilities. Use the replacements shown below. Opacity values remain numeric.

Spacing

Use gap utilities instead of margins for spacing between siblings:

<div class="flex gap-8">
    <div>Item 1</div>
    <div>Item 2</div>
</div>

Dark Mode

If existing pages and components support dark mode, new pages and components must support it the same way, typically using the dark: variant:

<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
    Content adapts to color scheme
</div>

Common Patterns

Flexbox Layout

<div class="flex items-center justify-between gap-4">
    <div>Left content</div>
    <div>Right content</div>
</div>

Grid Layout

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
    <div>Card 1</div>
    <div>Card 2</div>
    <div>Card 3</div>
</div>

NexoPOS modules: required utility prefix

When writing Tailwind inside a NexoPOS module (files under modules/*/Resources), always use a short module-specific prefix on the module CSS entry and on every module-owned utility. Core already ships an unprefixed Tailwind build in theme CSS; modules must not emit a second unprefixed copy.

/* modules/FooBar/Resources/css/style.css */
@import "tailwindcss" prefix(foo);

<!-- prefix first, then variants, then utility -->
<div class="foo:flex foo:gap-4 foo:md:grid-cols-2 foo:hover:underline">

With theme + breakpoint variants (if used): foo:dark:sm:flex — not dark:foo:sm:flex. The stack is incomplete without the utility (foo:dark:sm alone is invalid).

Do not prefix core component hooks (ns-button, ns-box, …). Prefer semantic theme tokens (foo:bg-box-background) over dark: for NexoPOS multi-theme compatibility. See create-nexopos-module → references/module-frontend.md and the nexopos-theming skill.

Common Pitfalls

• Using deprecated v3 utilities (bg-opacity-, flex-shrink-, etc.)
• Using @tailwind directives instead of @import "tailwindcss"
• Trying to use tailwind.config.js instead of CSS @theme directive
• Using margins for spacing between siblings instead of gap utilities
• Forgetting to add dark mode variants when the project uses dark mode
• Module CSS without prefix(...), or markup that omits the module prefix on utilities
• Putting the module prefix after variants (md:foo:flex) — prefix is always first
• In NexoPOS semantic status families, using *-primary or *-tertiary as a background; use *-secondary with text-white
• Applying box-elevation-hover to passive rows or cards that are not clickable