---
# === IDENTITY ===
id: software/migrations/sass-to-tailwind/2026
canonical_question: "How do I migrate from Sass/LESS to Tailwind CSS?"
aliases:
  - "Sass to Tailwind CSS migration guide"
  - "convert SCSS to Tailwind"
  - "replace Sass with Tailwind CSS"
  - "LESS to Tailwind migration"
  - "migrate preprocessor CSS to utility-first Tailwind"
  - "move from Sass variables and mixins to Tailwind"
  - "switch from LESS to Tailwind CSS v4"
entity_type: software_reference
domain: software > migrations > sass_to_tailwind
region: global
jurisdiction: global
temporal_scope: 2023-2026

# === VERIFICATION ===
last_verified: 2026-05-17
confidence: 0.93
freshness: evolving
version: 2.1
first_published: 2026-02-17

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: evolving
  last_breaking_change: "Tailwind CSS v4.2 (2026-02-18) — deprecated start-* / end-* in favor of inline-s-* / inline-e-* logical properties"
  next_review: 2026-11-13
  change_sensitivity: medium

# === CONSTRAINTS ===
constraints:
  - "Tailwind CSS v4 is incompatible with Sass, LESS, and Stylus — you cannot use @import 'tailwindcss' inside .scss or .less files"
  - "The official @tailwindcss/upgrade tool does not process .scss or .less files — Sass code must be manually converted to plain CSS"
  - "Tailwind v4 requires modern browsers: Chrome 111+, Safari 16.4+, Firefox 128+ — stay on v3.4 if you need older browser support"
  - "Never mix Tailwind's @import 'tailwindcss' with Sass partials in the same file — Lightning CSS cannot parse Sass syntax"
  - "CSS color-mix() (replacement for Sass darken/lighten) requires Safari 16.4+, Chrome 111+, Firefox 113+ — pre-define shades in @theme for wider support"
  - "Node.js 20+ is required for Tailwind v4 and the upgrade tool"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "User wants to migrate from Bootstrap to Tailwind (not from Sass itself)"
    use_instead: "Follow the official Tailwind upgrade guide; this unit assumes Sass/LESS source"
  - condition: "User wants to migrate from CSS Modules to Tailwind"
    use_instead: "Use utility classes directly in component markup; this unit covers preprocessor removal"
  - condition: "User only needs to upgrade Tailwind v3 to v4 (no Sass removal)"
    use_instead: "Run `npx @tailwindcss/upgrade` directly — the Sass conversion steps in this unit do not apply"

# === AGENT HINTS ===
inputs_needed:
  - key: current_setup
    question: "Is the project currently using Tailwind v3 alongside Sass, or is it pure Sass/LESS with no Tailwind?"
    type: choice
    options: ["Tailwind v3 + Sass", "Pure Sass/LESS (no Tailwind)", "Tailwind v4 + Sass (broken)"]
  - key: preprocessor
    question: "Which CSS preprocessor is the project using?"
    type: choice
    options: ["Sass/SCSS", "LESS", "Both"]
  - key: sass_complexity
    question: "How complex is the preprocessor usage?"
    type: choice
    options: ["Simple (variables, nesting only)", "Moderate (mixins, extends, maps)", "Complex (functions, loops, control flow)"]

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/software/migrations/sass-to-tailwind/2026"
suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-05-17)"

# === RELATED UNITS ===
related_kos:
  related_to:
    - id: "software/migrations/webpack-to-vite/2026"
      label: "Webpack to Vite Migration"
    - id: "software/migrations/javascript-to-typescript/2026"
      label: "JavaScript to TypeScript Migration"
  alternative_to:
    - id: "software/migrations/jquery-to-react/2026"
      label: "jQuery to React Migration (frontend stack modernization)"

# === SOURCES (8 authoritative sources) ===
# Types: official_docs, technical_blog, rfc_spec, academic_paper, community_resource, industry_report
# Reliability: high, moderate_high, moderate, moderate_low, low, authoritative
sources:
  - id: src1
    title: "Upgrade guide - Getting started - Tailwind CSS"
    author: Tailwind Labs
    url: https://tailwindcss.com/docs/upgrade-guide
    type: official_docs
    published: 2025-01-22
    reliability: authoritative
  - id: src2
    title: "Using with Preprocessors - Tailwind CSS v3"
    author: Tailwind Labs
    url: https://v3.tailwindcss.com/docs/using-with-preprocessors
    type: official_docs
    published: 2023-06-01
    reliability: authoritative
  - id: src3
    title: "Theme variables - Core concepts - Tailwind CSS"
    author: Tailwind Labs
    url: https://tailwindcss.com/docs/theme
    type: official_docs
    published: 2025-01-22
    reliability: authoritative
  - id: src4
    title: "Compatibility - Getting started - Tailwind CSS"
    author: Tailwind Labs
    url: https://tailwindcss.com/docs/compatibility
    type: official_docs
    published: 2025-01-22
    reliability: authoritative
  - id: src5
    title: "Migrating an Angular project (with Sass) to Tailwind CSS v4"
    author: Jits
    url: https://jits.dev/blog/migrating-angular-tailwind-v4/
    type: technical_blog
    published: 2025-03-15
    reliability: high
  - id: src6
    title: "Tailwind CSS 4 + Sass: Why They Don't Mix (And What To Do About It)"
    author: Blueprintblog
    url: https://medium.com/@genildocs/tailwind-css-4-sass-why-they-dont-mix-and-what-to-do-about-it-94598e0f1342
    type: technical_blog
    published: 2025-04-10
    reliability: moderate_high
  - id: src7
    title: "What's New in Tailwind CSS 4.0: Migration Guide (2026)"
    author: DesignRevision
    url: https://designrevision.com/blog/tailwind-4-migration
    type: technical_blog
    published: 2026-01-15
    reliability: high
  - id: src8
    title: "Tailwind CSS v4.1: Text shadows, masks, and tons more"
    author: Tailwind Labs
    url: https://tailwindcss.com/blog/tailwindcss-v4-1
    type: official_docs
    published: 2025-04-03
    reliability: authoritative
  - id: src9
    title: "Tailwind CSS v4.3: Scrollbars, new colors, and more"
    author: Tailwind Labs
    url: https://tailwindcss.com/blog/tailwindcss-v4-3
    type: official_docs
    published: 2026-05-08
    reliability: authoritative
  - id: src10
    title: "New Colors Added in Tailwind CSS v4.2"
    author: Laravel News
    url: https://laravel-news.com/tailwindcss-4-2-0
    type: technical_blog
    published: 2026-02-18
    reliability: high
---

# How to Migrate from Sass/LESS to Tailwind CSS

## TL;DR

- **Bottom line**: Migrate incrementally -- replace Sass/LESS variables with Tailwind's `@theme` CSS custom properties, convert mixins to utility classes or `@apply` rules, replace nesting with CSS-native nesting, then remove the preprocessor once no references remain.
- **Key tool/command**: `npx @tailwindcss/upgrade` (automates ~90% of Tailwind v3-to-v4 migration including class renames, config-to-CSS conversion, and template updates; Sass files require manual conversion)
- **Watch out for**: Tailwind CSS v4 is **not compatible with Sass/LESS** -- you cannot use `@import "tailwindcss"` inside `.scss` or `.less` files. The Oxide engine (Lightning CSS) cannot parse preprocessor syntax. Preprocessor code must be converted to plain CSS first. [src4]
- **Works with**: Tailwind CSS v4.1+, Node.js 20+, any framework (React, Vue, Angular, Svelte, plain HTML). Sass 1.x, LESS 4.x as starting points.

## Constraints
<!-- Agents: read this section before recommending any action from this unit.
     These are hard constraints that must not be violated. -->

- Tailwind CSS v4 is a complete CSS build tool that replaces preprocessors -- think of Tailwind itself as your preprocessor. Sass, LESS, and Stylus cannot be used alongside it in the same file. [src4]
- The `@tailwindcss/upgrade` tool only processes `.css` files. It will skip or error on `.scss`/`.less` files. You must manually convert preprocessor code to plain CSS before or after running the tool. [src1, src5]
- Tailwind v4 requires Chrome 111+, Safari 16.4+, Firefox 128+. If your project must support older browsers, stay on Tailwind v3.4 (the last version supporting Sass coexistence). [src4]
- Never let Tailwind's `@import "tailwindcss"` appear in a `.scss` file -- Lightning CSS will crash with parse errors on Sass syntax. Keep Tailwind directives in `.css` files only. [src6]
- CSS `color-mix()` (the replacement for Sass `darken()`/`lighten()`) requires Safari 16.4+, Chrome 111+, Firefox 113+. For wider browser support, pre-define all color shades in `@theme`. [src3]
- Node.js 20+ is required for the Tailwind v4 CLI and upgrade tool. [src1]

## Quick Reference

| Sass/LESS Pattern | Tailwind Equivalent | Example |
|---|---|---|
| `$primary: #3B82F6;` / `@primary: #3B82F6;` | `@theme { --color-primary: #3B82F6; }` | `class="text-primary bg-primary/10"` |
| `@mixin button($bg) { ... }` | Utility classes or `@apply` | `class="px-4 py-2 rounded bg-blue-500"` |
| `@include respond-to('md') { ... }` | Responsive prefix | `class="p-4 md:p-8 lg:p-12"` |
| `darken($color, 10%)` / `lighten()` | Opacity modifier or `color-mix()` | `class="bg-blue-500/90"` or `color-mix(in oklch, var(--color-blue-500), black 10%)` |
| `&:hover { color: red; }` | State variant prefix | `class="hover:text-red-500"` |
| `@extend .btn-base;` | Component extraction with `@apply` | `.btn { @apply px-4 py-2 rounded; }` |
| `.card { .title { ... } }` nesting | CSS-native nesting or flat utilities | `.card { & .title { @apply text-lg font-bold; } }` |
| `@for $i from 1 through 12 { ... }` | Grid/spacing scale utilities | `class="grid-cols-1 md:grid-cols-6 lg:grid-cols-12"` |
| `@import 'variables'; @import 'mixins';` | `@import "tailwindcss";` | Single import replaces all partials |
| `map-get($colors, 'primary')` | CSS variable reference | `var(--color-primary)` or `theme(colors.primary)` |
| `@each $name, $color in $colors { ... }` | `@theme` block generates all utilities | `@theme { --color-brand: #38bdf8; }` auto-generates `text-brand`, `bg-brand`, etc. |
| `$spacing-unit: 8px; padding: $spacing-unit * 2;` | Spacing scale | `class="p-4"` (= 1rem = 16px by default) |
| `@media (min-width: $breakpoint-md) { ... }` | Responsive prefix | `class="md:flex md:gap-4"` |
| `%placeholder { ... }` silent extends | `@utility` directive (v4) | `@utility glass { backdrop-filter: blur(12px); }` |
| `!default` variable flags | `@theme` with CSS custom property fallbacks | `--color-accent: var(--color-brand, #3B82F6);` |

## Decision Tree

```
START
├── Is the project currently on Tailwind v3 with Sass alongside?
│   ├── YES → First upgrade to Tailwind v4 (run npx @tailwindcss/upgrade), then remove Sass
│   └── NO ↓
├── Is the project pure Sass/LESS with no Tailwind at all?
│   ├── YES → Install Tailwind v4, run both systems in parallel, migrate file-by-file
│   └── NO ↓
├── Does the Sass/LESS codebase use complex mixins with parameters?
│   ├── YES → Extract to component classes with @apply, or convert to CSS custom properties + calc()
│   └── NO ↓
├── Does the project use Sass maps or LESS maps for design tokens?
│   ├── YES → Convert to @theme block with CSS custom properties (auto-generates utility classes)
│   └── NO ↓
├── Are there many @extend / placeholder selectors?
│   ├── YES → Replace with @apply or direct utility classes in markup
│   └── NO ↓
├── Does the project use Sass color functions (darken, lighten, mix)?
│   ├── YES → Replace with Tailwind opacity modifiers, color-mix(), or pre-defined shades in @theme
│   └── NO ↓
└── DEFAULT → Replace Sass/LESS features one-by-one: variables → @theme, nesting → CSS nesting, imports → @import "tailwindcss", then delete .scss/.less files
```

## Step-by-Step Guide

### 1. Audit the Sass/LESS surface area

Quantify what needs migrating: count variables, mixins, extends, nested rules, and custom functions. This tells you migration complexity and timeline. [src5]

```bash
# For Sass/SCSS projects
find . -name '*.scss' -o -name '*.sass' | xargs wc -l | tail -1
grep -rn '\$' --include='*.scss' | grep -v node_modules | wc -l        # variables
grep -rn '@mixin' --include='*.scss' | wc -l                            # mixins
grep -rn '@include' --include='*.scss' | wc -l                          # mixin usages
grep -rn '@extend' --include='*.scss' | wc -l                           # extends
grep -rn '@import' --include='*.scss' | wc -l                           # partial imports

# For LESS projects
find . -name '*.less' | xargs wc -l | tail -1
grep -rn '@' --include='*.less' | grep -v node_modules | wc -l          # variables
grep -rn '\.mixin' --include='*.less' | wc -l                           # mixins
```

**Verify**: A small project has <500 lines and <20 variables. Medium is 500-5000 lines. Large is >5000 lines. Estimate 1-2 hours per 500 lines for manual conversion.

### 2. Install Tailwind CSS v4 alongside the existing preprocessor

Run both systems in parallel during migration. Tailwind processes `.css` files; Sass processes `.scss` files. They do not conflict if kept in separate files. [src1]

```bash
# Install Tailwind v4 (requires Node.js 20+)
npm install tailwindcss @tailwindcss/postcss

# For Vite projects (recommended — fastest builds)
npm install @tailwindcss/vite

# For CLI-only usage
npm install @tailwindcss/cli
```

Create your Tailwind entry point as a `.css` file (NOT `.scss`):

```css
/* src/tailwind.css */
@import "tailwindcss";
```

**Verify**: `npx @tailwindcss/cli -i src/tailwind.css -o dist/output.css` compiles without errors.

### 3. Convert Sass/LESS variables to Tailwind @theme

Move design tokens from `$variables` or `@variables` to Tailwind's `@theme` block. Each CSS custom property automatically generates utility classes. Variables defined outside `@theme` (e.g., in `:root`) do NOT generate utilities. [src3, src7]

```css
/* BEFORE: _variables.scss */
/* $primary: #3B82F6;
   $secondary: #10B981;
   $font-sans: 'Inter', sans-serif;
   $spacing-unit: 8px;
   $radius-md: 0.375rem; */

/* AFTER: tailwind.css */
@import "tailwindcss";

@theme {
  --color-primary: #3B82F6;
  --color-secondary: #10B981;
  --font-sans: 'Inter', sans-serif;
  --spacing-unit: 0.5rem;
  --radius-md: 0.375rem;
}
```

**Verify**: `class="text-primary bg-secondary"` renders correct colors in the browser.

### 4. Replace mixins with utility classes or @apply rules

Sass mixins that output simple property groups become utility classes in HTML. Complex mixins with parameters become custom CSS with `@apply` or CSS custom properties. In v4, use the `@utility` directive instead of `@layer utilities`. [src2, src6]

```scss
// BEFORE: Sass mixin
@mixin card-style($padding: 16px, $radius: 8px) {
  padding: $padding;
  border-radius: $radius;
  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
  background: white;
}
.card { @include card-style; }
.card-lg { @include card-style(24px, 12px); }
```

```html
<!-- AFTER: Tailwind utility classes -->
<div class="p-4 rounded-lg shadow-sm bg-white">...</div>
<div class="p-6 rounded-xl shadow-sm bg-white">...</div>
```

For truly reusable patterns, use `@utility` in CSS (v4 replacement for `@layer utilities`):

```css
/* AFTER: @utility for component classes */
@utility card {
  @apply p-4 rounded-lg shadow-sm bg-white;
}
@utility card-lg {
  @apply p-6 rounded-xl shadow-sm bg-white;
}
```

**Verify**: Visual diff shows identical rendering before and after mixin removal.

### 5. Convert nesting and media queries to Tailwind patterns

Replace Sass nesting with CSS-native nesting (supported in v4 via Lightning CSS) or flat utility classes. Replace `@media` queries with responsive prefixes. [src1]

```scss
// BEFORE: Sass nesting + media queries
.sidebar {
  width: 100%;
  padding: 1rem;

  @media (min-width: 768px) {
    width: 250px;
    padding: 2rem;
  }

  .nav-item {
    color: gray;
    &:hover {
      color: blue;
    }
  }
}
```

```html
<!-- AFTER: Tailwind utility classes -->
<aside class="w-full p-4 md:w-[250px] md:p-8">
  <a class="text-gray-500 hover:text-blue-500">...</a>
</aside>
```

**Verify**: Resize browser window -- responsive behavior matches the original Sass media query breakpoints.

### 6. Remove @extend and @import partials

Replace Sass partials with Tailwind's single `@import "tailwindcss"`. Replace `@extend` with direct utility classes or `@apply`. Tailwind v4 automatically bundles imported CSS files without separate preprocessing. [src1, src2, src4]

```scss
// BEFORE: Sass partials and extends
@import 'variables';
@import 'mixins';
@import 'base';
@import 'components/buttons';
@import 'components/cards';

%btn-base {
  display: inline-flex;
  align-items: center;
  padding: 0.5rem 1rem;
  border-radius: 0.375rem;
}
.btn-primary { @extend %btn-base; background: $primary; color: white; }
.btn-secondary { @extend %btn-base; background: $secondary; color: white; }
```

```css
/* AFTER: Tailwind CSS */
@import "tailwindcss";

@theme {
  --color-primary: #3B82F6;
  --color-secondary: #10B981;
}

@utility btn-primary {
  @apply inline-flex items-center px-4 py-2 rounded-md bg-primary text-white;
}
@utility btn-secondary {
  @apply inline-flex items-center px-4 py-2 rounded-md bg-secondary text-white;
}
```

**Verify**: `grep -rn '@import\|@extend' --include='*.scss'` returns zero results after migration.

### 7. Handle Vue/Svelte/Astro component styles

In Tailwind v4, `@apply` inside component `<style>` blocks requires a `@reference` directive pointing to your main CSS file. Alternatively, use utility classes directly in markup (recommended). [src1, src4]

```html
<!-- Vue/Svelte: If you must use @apply in scoped styles -->
<style scoped>
@reference "../../app.css";
.card-title { @apply text-xl font-bold text-gray-900; }
</style>
```

**Verify**: Component renders correctly with `@apply` styles applied.

### 8. Delete Sass/LESS dependencies and config

Once all `.scss` / `.less` files are converted, remove the preprocessor toolchain. [src5]

```bash
# Remove Sass
npm uninstall sass sass-loader node-sass

# Remove LESS
npm uninstall less less-loader

# Remove preprocessor config from bundler
# Delete any sass-specific webpack/vite config entries

# Delete all .scss / .less files
find . -name '*.scss' -o -name '*.less' | grep -v node_modules | xargs rm

# Update build scripts in package.json
# Replace any "sass" or "lessc" commands with Tailwind CLI
```

**Verify**: `npm ls sass less` shows no preprocessor packages. `find . -name '*.scss' -o -name '*.less' | grep -v node_modules` returns empty. App builds and runs correctly.

## Code Examples

### JavaScript/PostCSS: Tailwind v4 configuration replacing Sass variables and mixins

> Full script: [javascript-postcss-tailwind-v4-configuration-repla.txt](scripts/javascript-postcss-tailwind-v4-configuration-repla.txt) (31 lines)

```css
/* Input:  A Sass-based design system with variables, mixins, and custom breakpoints
   Output: Equivalent Tailwind v4 CSS-first configuration */
@import "tailwindcss";
/* Design tokens — replaces $variables in _variables.scss */
@theme {
# ... (see full script)
```

### TypeScript/React: Component refactored from Sass modules to Tailwind

> Full script: [typescript-react-component-refactored-from-sass-mo.ts](scripts/typescript-react-component-refactored-from-sass-mo.ts) (38 lines)

```typescript
// Input:  React component using CSS Modules with Sass (.module.scss)
// Output: Same component using Tailwind utility classes
// BEFORE: Button.module.scss
// .button {
//   @include button-base;
# ... (see full script)
```

### Vue SFC: Migrating scoped Sass styles to Tailwind v4

> Full script: [vue-sfc-migrating-scoped-sass-styles-to-tailwind-v.txt](scripts/vue-sfc-migrating-scoped-sass-styles-to-tailwind-v.txt) (38 lines)

```html
<!-- Input:  Vue component using <style lang="scss" scoped>
     Output: Same component using Tailwind utilities + @reference -->
<!-- BEFORE: Vue component with scoped Sass -->
<!-- <style lang="scss" scoped>
@import '@/styles/variables';
# ... (see full script)
```

## Anti-Patterns

### Wrong: Using Sass inside Tailwind v4 CSS files

```css
/* BAD — Sass syntax in a file processed by Tailwind v4 */
@import "tailwindcss";

$primary: #3B82F6;  /* Sass variable — will not compile */

.btn {
  background: $primary;
  @include responsive-padding;  /* Sass mixin — will fail */
}
```

### Correct: Use @theme and CSS custom properties

```css
/* GOOD — Pure CSS with Tailwind v4 @theme */
@import "tailwindcss";

@theme {
  --color-primary: #3B82F6;
}

.btn {
  background: var(--color-primary);
  @apply px-4 py-2 md:px-6 md:py-3;
}
```

### Wrong: Converting every Sass class to @apply

```css
/* BAD — Re-creating Sass abstractions with @apply defeats the purpose */
.container { @apply mx-auto max-w-7xl px-4; }
.heading-1 { @apply text-4xl font-bold text-gray-900; }
.heading-2 { @apply text-3xl font-semibold text-gray-800; }
.heading-3 { @apply text-2xl font-medium text-gray-700; }
.paragraph { @apply text-base text-gray-600 leading-relaxed; }
.link { @apply text-blue-500 underline hover:text-blue-700; }
/* 200 more classes... You just rebuilt Sass with extra steps */
```

### Correct: Use utility classes directly in markup

```html
<!-- GOOD — Utility classes in HTML, extract only truly reusable components -->
<h1 class="text-4xl font-bold text-gray-900">Title</h1>
<p class="text-base text-gray-600 leading-relaxed">Content</p>
<a class="text-blue-500 underline hover:text-blue-700" href="#">Link</a>

<!-- Only extract when repeated across 3+ locations -->
<!-- Use @utility for shared component patterns, not 1:1 class replacements -->
```

### Wrong: Running the Tailwind upgrade tool on .scss files

```bash
# BAD — The upgrade tool does not recognize .scss files
npx @tailwindcss/upgrade
# "Cannot find any CSS files that reference Tailwind CSS"
```

### Correct: Create a temporary .css file, upgrade, then apply changes

```bash
# GOOD — Extract Tailwind directives to a temp .css file first [src5]
# 1. Create tailwind.tmp.css with only Tailwind imports (no Sass)
echo '@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";' > tailwind.tmp.css

# 2. Run the upgrade tool
npx @tailwindcss/upgrade --force

# 3. Review git diff, apply changes to your real styles
git diff tailwind.tmp.css

# 4. Clean up
rm tailwind.tmp.css
```

### Wrong: Keeping Sass for "just nesting" alongside Tailwind v4

```scss
// BAD — Running Sass just for nesting when CSS nesting is native
// sass-loader + Tailwind = two build steps, potential conflicts
.card {
  .title {
    font-size: 1.25rem;
    font-weight: bold;
  }
  .body {
    padding: 1rem;
  }
}
```

### Correct: Use CSS-native nesting (supported in all modern browsers)

```css
/* GOOD — CSS nesting works natively in Tailwind v4 */
.card {
  & .title {
    @apply text-xl font-bold;
  }
  & .body {
    @apply p-4;
  }
}
```

### Wrong: Defining design tokens in :root instead of @theme

```css
/* BAD — Variables in :root do not generate Tailwind utilities */
:root {
  --color-brand: #3B82F6;
  --color-accent: #10B981;
}
/* class="text-brand" will NOT work */
```

### Correct: Use @theme for any token that needs utility classes

```css
/* GOOD — @theme variables auto-generate utilities [src3] */
@theme {
  --color-brand: #3B82F6;
  --color-accent: #10B981;
}
/* class="text-brand bg-accent/50" now works */
```

## Common Pitfalls

- **Tailwind v4 crashes on `.scss`/`.less` files**: Tailwind's Oxide engine (built on Lightning CSS) cannot parse Sass or LESS syntax. Fix: Keep Tailwind directives in `.css` files only. Run preprocessor and Tailwind as separate build steps during migration. [src1, src6]
- **`theme()` function unavailable in Sass**: Since Sass compiles before PostCSS/Tailwind, Tailwind's `theme()` function cannot be used inside `.scss` files. Fix: Use CSS custom properties (`var(--color-primary)`) instead, which work everywhere. [src2]
- **`@apply` with `!important` fails in Sass**: Sass misinterprets the `!important` flag. Fix: Use interpolation syntax: `@apply bg-red-500 #{!important};`. Better yet, migrate to plain `.css` where this is not an issue. [src2]
- **Overusing @apply creates "Sass with extra steps"**: Converting every Sass class to an `@apply` rule negates Tailwind's benefits (no dead-code elimination, same abstraction overhead). Fix: Apply utilities directly in HTML markup. Reserve `@apply` / `@utility` for patterns repeated in 3+ places. [src1]
- **Sass color functions (`darken()`, `lighten()`, `mix()`) have no direct Tailwind equivalent**: These are compile-time Sass functions. Fix: Use Tailwind opacity modifiers (`bg-blue-500/80`), CSS `color-mix()` function, or define color shades in `@theme`. [src3]
- **Missing `@reference` in Vue/Svelte scoped styles**: In Tailwind v4, `@apply` in component `<style>` blocks requires a `@reference` directive pointing to your main CSS file. Fix: Add `@reference "../../app.css";` at the top of the `<style>` block. [src1, src4]
- **Design tokens not generating utility classes**: Variables defined outside `@theme` do not generate Tailwind utilities. Fix: All design tokens that need utility classes must be inside the `@theme { }` block, not in plain `:root { }`. [src3, src7]
- **Sass `@for` / `@each` loops for grid classes**: Tailwind's JIT engine already generates these on-demand. Fix: Delete Sass loops and use Tailwind's built-in `grid-cols-*`, `gap-*`, and arbitrary value syntax (`grid-cols-[repeat(auto-fill,minmax(250px,1fr))]`). [src7]
- **LESS variable syntax collides with CSS at-rules**: LESS variables (`@variable`) look identical to CSS at-rules (`@media`, `@import`, `@theme`). Fix: Convert LESS variables to CSS custom properties (`--variable`) early in the migration to avoid parser confusion. [src4]

## Diagnostic Commands

```bash
# Count remaining Sass/LESS files
find . -name '*.scss' -o -name '*.sass' -o -name '*.less' | grep -v node_modules | wc -l

# Count Sass variable references still in use
grep -rn '\$[a-zA-Z]' --include='*.scss' --include='*.vue' --include='*.svelte' | grep -v node_modules | wc -l

# Count LESS variable references
grep -rn '@[a-zA-Z]' --include='*.less' | grep -v node_modules | grep -v '@media\|@import\|@charset\|@keyframes\|@font-face' | wc -l

# Check for Sass dependencies in package.json
node -e "const p=require('./package.json'); const deps={...p.dependencies,...p.devDependencies}; const sass=Object.keys(deps).filter(k=>k.match(/sass|less|stylus/i)); console.log(sass.length?'Still installed: '+sass.join(', '):'Clean — no preprocessor deps');"

# Verify Tailwind v4 is working
npx @tailwindcss/cli -i src/app.css -o /dev/null 2>&1 && echo "Tailwind v4 OK" || echo "Tailwind build failed"

# Check generated CSS size (should shrink after removing preprocessor overhead)
npx @tailwindcss/cli -i src/app.css -o dist/output.css && wc -c dist/output.css

# Find any remaining @import of Sass partials
grep -rn "@import '.*'" --include='*.scss' --include='*.css' | grep -v node_modules | grep -v tailwindcss

# Verify Node.js version meets minimum requirement
node -v  # Must be v20.0.0 or higher for Tailwind v4
```

## Version History & Compatibility

| Version | Status | Breaking Changes | Migration Notes |
|---|---|---|---|
| Tailwind v4.3 (May 2026) | Current | First-party scrollbar utilities (`scrollbar-thin`, `scrollbar-thumb-*`, `scrollbar-gutter-stable`), `@container-size` block-size container queries, `zoom-*` + `tab-*` utilities, stacked `@variant` support (`hover:focus`), default-value functional utilities | No breaking changes; no Sass-specific changes. Replace Sass scrollbar mixins with native `scrollbar-*` utilities. [src9] |
| Tailwind v4.2 (Feb 2026) | Current | Four new color palettes (`mauve`, `olive`, `mist`, `taupe`), official `@tailwindcss/webpack` plugin (2.17× faster than PostCSS), full logical-property utilities (`pbs-*`, `pbe-*`, `mbs-*`, `mbe-*`, `border-bs`, `inset-bs-*`, `inline-*`, `block-*`), `font-features-*`. **`start-*` / `end-*` deprecated** in favor of `inline-s-*` / `inline-e-*` | After upgrade, run `grep -rn 'class=".*\b\(start\|end\)-[0-9]'` and rename to `inline-s-*` / `inline-e-*`. Webpack-based Sass projects can now drop PostCSS and use the official Webpack plugin directly. [src10] |
| Tailwind v4.1 (Apr 2025) | Maintenance | Text shadows, masks, `@source not/inline()`, improved browser fallbacks | Minor patch on v4.0 -- no Sass-specific changes |
| Tailwind v4.0 (Jan 2025) | Maintenance | Oxide engine (Lightning CSS), `@import "tailwindcss"` replaces `@tailwind` directives, CSS-first `@theme` config, **no Sass/LESS support** | `postcss-import` and `autoprefixer` are no longer needed; Sass files must be converted to CSS |
| Tailwind v3.4 (Dec 2023) | LTS | Last version supporting Sass/LESS coexistence | Stay here if you cannot remove Sass yet |
| Tailwind v3.0 (Dec 2021) | Maintenance | JIT engine became default | Content paths required in `tailwind.config.js` |
| Sass 1.x (Dart Sass) | Current | `@import` deprecated in favor of `@use`/`@forward` | Convert Sass `@import` to `@use` before migrating to Tailwind |
| LESS 4.x | Current | — | LESS variables (`@var`) conflict with CSS at-rules; rename before converting |

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Starting a new project or major redesign | Sass codebase is stable and team is productive | Keep Sass, add Tailwind incrementally |
| Design system is defined in design tokens (colors, spacing, typography) | Heavy use of Sass programmatic features (functions, control flow, maps) | Keep Sass for complex theming, use Tailwind for layout/utilities |
| Team wants utility-first workflow and faster prototyping | Project has <500 lines of CSS and no complexity | Vanilla CSS or CSS Modules |
| Bundle size is a concern (Tailwind purges unused CSS) | Need to support IE11 or Safari <16.4 | Stay on Tailwind v3 + Sass, or use PostCSS alone |
| You want to eliminate Sass build step overhead | Library/design system consumed by multiple apps with varying build setups | CSS custom properties + vanilla CSS (most portable) |

## Important Caveats

- Tailwind v4 requires modern browsers: Safari 16.4+, Chrome 111+, Firefox 128+. If your audience needs older browsers, stay on Tailwind v3.4 which supports Sass coexistence.
- The automated `@tailwindcss/upgrade` tool does not process `.scss` or `.less` files. You must manually convert preprocessor code to plain CSS before or after running the tool.
- `@apply` is still supported in v4 but is considered an escape hatch. Tailwind Labs recommends using utility classes directly in markup for most cases, and the `@utility` directive for truly reusable component patterns.
- LESS variable syntax (`@variable`) collides with CSS at-rules (`@media`, `@import`, `@theme`). During migration, this can cause confusing parser errors. Convert LESS variables to CSS custom properties early.
- CSS `color-mix()` (the replacement for Sass `darken()`/`lighten()`) requires Safari 16.4+, Chrome 111+, Firefox 113+. For wider support, pre-define color shades in `@theme`.
- Tailwind v4 builds are up to 5x faster for full builds and 100x faster for incremental builds compared to v3, thanks to the Rust-based Oxide engine. This speed improvement alone can justify removing the Sass build step.
- In v4.1, `@source not` can exclude legacy Sass directories from Tailwind's class detection scanning, speeding up builds during incremental migration. [src8]
- **v4.2 (Feb 2026)** deprecated `start-*` and `end-*` utilities in favor of `inline-s-*` / `inline-e-*`. If your Sass codebase used logical-direction mixins, map them straight to the new names rather than the deprecated ones. [src10]
- **v4.3 (May 2026)** added first-party scrollbar utilities — `scrollbar-thin`, `scrollbar-thumb-*`, `scrollbar-track-*`, `scrollbar-gutter-stable`. Sass projects that ship custom `::-webkit-scrollbar` selectors can replace them with these utilities and drop the Sass file entirely. [src9]
- **v4.3 `@container-size`** enables block-direction container queries — useful when migrating Sass `@include respond-to($height)` macros that previously required JavaScript hacks. [src9]
- **Webpack users**: v4.2 introduced the official `@tailwindcss/webpack` plugin (~2.17× faster than PostCSS). After Sass removal, switch from `postcss-loader + @tailwindcss/postcss` to the dedicated webpack loader for a free build speedup. [src10]

## Related Units
<!-- Generated from related_kos frontmatter -->

- [Webpack to Vite Migration](/software/migrations/webpack-to-vite/2026)
- [jQuery to React Migration](/software/migrations/jquery-to-react/2026)
- [JavaScript to TypeScript Migration](/software/migrations/javascript-to-typescript/2026)