Fluidwind by MAJOR Digital

The hassle-free way to get started with Tailwind spacing. This CLI tool generates customisable spacing values for TailwindCSS v4 using t-shirt sizing that adapts across breakpoints.

Features

✨ Tailwind-suited Sizing - Define space tokens using t-shirt sizing (xs, sm, md, lg, xl, etc.) 📱 Fully Responsive - Spacing values automatically adjust at different breakpoints 🎯 Affects All Spacing Utilities - Creates --spacing-* variables which target spacing and sizing utilities 🔧 Interactive CLI - Easy-to-use prompts 📂 Auto-Detection - Finds your Tailwind CSS file automatically ♻️ Re-runnable - Update your spacing values anytime

Requirements

• Node.js >= 14.0.0
• Tailwind CSS v4.0.0 or higher

Installation

You can run this tool directly using npx without installation:

npx fluidwind

Or install it globally:

npm install -g fluidwind

Usage

1. Navigate to your project directory:

cd my-tailwind-project

2. Run Fluidwind:

npx fluidwind

3. Follow the interactive prompts:

• Define your smallest and largest t-shirt sizes (e.g., xs to 5xl)
• Fluidwind will find your CSS file with @import 'tailwindcss'
• Enter spacing values for each size at each breakpoint
• Press Enter to skip a breakpoint (inherits from previous)
• Press Escape to go back and edit the previous value

4. Once generated, use the created tokens in any spacing and sizing utility:

<!-- Margin -->
<div class="m-xs">...</div>
<div class="mt-lg mb-md">...</div>

<!-- Padding -->
<div class="p-xl">...</div>
<div class="px-sm py-md">...</div>

<!-- Gap -->
<div class="flex gap-md">...</div>
<div class="grid gap-x-lg gap-y-sm">...</div>

<!-- Width -->
<div class="h-lg w-sm">...</div>
<div class="size-xl">...</div>

Local development testing

Using npm link (recommended)

In the CLI tool directory:

npm link

In your test project:

npm link fluidwind
fluidwind

Direct path execution

node /path/to/cli-tool/dist/cli.js

Using packed tarball

npm pack
npm install /path/to/fluidwind-1.0.0.tgz

Example

$ npx fluidwind

==================================================
     TailwindCSS Responsive Spacing Generator
==================================================

Step 1: Define T-Shirt Sizing Range

T-shirt sizing format: 2xs, xs, sm, md, lg, xl, 2xl
What is the smallest size?: xs
What is the largest size?: 5xl

✓ Size range: xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl

Step 2: Locate CSS File

✓ Found: /path/to/project/src/app.css

Step 3: Define Spacing Values

Enter pixel values for each breakpoint
Enter values in pixels (e.g., 16 for 16px).
Press Enter to skip a breakpoint.
Press Escape to edit the previous value.

Size: xs
  base (0px): 4
  sm (640px): 6
  md (768px): 8
  lg (1024px): 
  xl (1280px): 
  2xl (1536px): 

Size: sm
  base (0px): 8
  sm (640px): 12
  md (768px): 16
  lg (1024px): 
  xl (1280px): 
  2xl (1536px): 

...

✓ Success! Responsive spacing variables have been added to /path/to/project/src/app.css

You can now use classes like: m-xs, p-5xl, gap-md
These will automatically adjust at different breakpoints!

How Fluidwind works

Fluidwind generates global CSS variables inside the :root selector that are then inserted into Tailwind's @theme directive. The generated CSS adheres to Tailwind v4 patterns which allows the use of created tokens in spacing and sizing utilities.

@import 'tailwindcss';

:root {
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 12px;
  --spacing-lg: 16px;
  --spacing-xl: 24px;
}

@media (width >= 640px) {
  :root {
    --spacing-xs: 6px;
    --spacing-sm: 12px;
    --spacing-md: 16px;
    --spacing-lg: 20px;
    --spacing-xl: 28px;
  }
}

@media (width >= 768px) {
  :root {
    --spacing-xs: 8px;
    --spacing-sm: 16px;
    --spacing-md: 20px;
    --spacing-lg: 24px;
    --spacing-xl: 32px;
  }
}

@theme {
  --spacing-xs: var(--spacing-xs);
  --spacing-sm: var(--spacing-sm);
  --spacing-md: var(--spacing-md);
  --spacing-lg: var(--spacing-lg);
  --spacing-xl: var(--spacing-xl);
}

Available breakpoints

By default, Fluidwind supports default TailwindCSS default breakpoints:

| Breakpoint prefix | Minimum width | CSS | | ----------------- | -------------- | --------------------------------- | | sm | 40rem (640px) | @media (width >= 40rem) { ... } | | md | 48rem (768px) | @media (width >= 48rem) { ... } | | lg | 64rem (1024px) | @media (width >= 64rem) { ... } | | xl | 80rem (1280px) | @media (width >= 80rem) { ... } | | 2xl | 96rem (1536px) | @media (width >= 96rem) { ... } |

The base value defined first is a mobile-first value which will be overridden by the first breakpoint defined.

Custom breakpoints

If you have custom breakpoints defined, Fluidwind will detect and insert these breakpoints in (so for example, if an xs breakpoint is defined with a width >= 480px breakpoint value, it will be inserted between base and sm).

T-shirt sizes

Fluidwind uses t-shirt sizing for token names to maintain consistency with Tailwind's existing naming conventions, making spacing tokens feel native to the framework.

| Scale | Plain English | | ----- | ------------- | | 2xs | 2 extra small | | xs | extra small | | sm | small | | md | medium | | lg | large | | xl | extra large. | | 2xl | 2 extra large |

Re-running Fluidwind

You can run Fluidwind multiple times. It will:

• Detect existing responsive spacing variables
• Replace them with new values
• Preserve the rest of your CSS file

CSS file detection

Fluidwind automatically searches for CSS files containing @import 'tailwindcss' in common locations:

Common directories searched:

• src/
• app/
• styles/
• assets/
• css/

Common filenames searched:

• app.css
• index.css
• globals.css
• main.css
• styles.css
• tailwind.css

Fluidwind generates all possible path combinations and validates them with regex patterns to find your Tailwind CSS file.

If no file is found, you can:

1. Create a new file at src/app.css (recommended)
2. Specify a custom path

Tips

2. Use Pixel Values: Enter values in pixels (e.g., 16 for 16px)
3. Enter to Skip Breakpoints: Press Enter to skip and inherit from the previous breakpoint
4. Escape (Esc) to Navigate Back: Press Escape to go back and edit the previous value
5. Ctrl+C to Exit: Gracefully exit at any time

Compatibility

This tool is designed specifically for Tailwind CSS v4 which uses:

• CSS imports instead of @tailwind directives
• Native CSS custom properties for theming
• The @theme directive for customization

For Tailwind CSS v3 projects, please use the v3-compatible configuration approach.

License

MIT

Author

MAJOR Digital

Contributing

Issues and pull requests are welcome!