npm package: @majorlabs/fluidwind
Description: Generate responsive spacing values for TailwindCSS v4 using t-shirt sizing that adapts across breakpoints
Author: MAJOR Digital
Latest version: 1.1.1

# Fluidwind

The hassle-free way to get started with Tailwind spacing. This CLI tool lets you generate t-shirt tokens to be used on spacing and sizing utilities which adapt to defined breakpoints for TailwindCSS v4.

```html
<!-- From... -->
<div class="px-2 sm:px-4 md:px-6 lg:px-8 xl:px-10 2xl:px-12">...</div>

<!-- To... -->
 <div class="px-sm">...</div>
```

## 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 spacing and sizing utilities**: Creates `--spacing-container-*` 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:

```bash
npx @majorlabs/fluidwind
```

Or install it globally:

```bash
npm install -g @majorlabs/fluidwind
```

## Usage

1. Navigate to your project directory:
```bash
cd my-tailwind-project
```

2. Run Fluidwind:
```bash
npx @majorlabs/fluidwind
```

3. Follow the interactive prompts:
  - Define your smallest and largest t-shirt sizes (e.g., xs to 5xl)
  - Choose a placeholder word for your spacing variables (default: container)
  - 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**:

```html
<!-- 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:
```bash
npm link
```

In your test project:
```bash
npm link @majorlabs/fluidwind
@majorlabs/fluidwind
```

### Direct path execution

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

### Using packed tarball

```bash
npm pack
npm install /path/to/majorlabs-fluidwind-1.1.0.tgz
```

## Example

```bash
$ npx @majorlabs/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

To avoid Tailwind spacing and sizing utilities being overridden, we prepend a placeholder word to the t-shirt tokens used.
Enter placeholder word (default: container): 

✓ Placeholder: container

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.

```css
@import 'tailwindcss';

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

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

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

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

## Placeholder customization

To prevent conflicts with Tailwind's default spacing and sizing utilities, Fluidwind prepends a placeholder word to your t-shirt tokens. By default, this is `container`, which generates variables like `--spacing-container-sm`, `--spacing-container-md`, etc.

You can customize this placeholder during the CLI setup to use any valid CSS identifier:

- Default: `container` → `--spacing-container-sm`
- Custom: `fluid` → `--spacing-fluid-sm`
- Custom: `space` → `--spacing-space-lg`

This approach ensures your custom spacing tokens don't override Tailwind's built-in utilities while keeping the variable names semantic and organized.

## 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)
4. **Enter to Skip Breakpoints**: Press Enter to skip and inherit from the previous breakpoint
5. **Escape (Esc) to Navigate Back**: Press Escape to go back and edit the previous value
6. **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!