Your designer draws the desktop page on one frame: 1440×900, or whatever size they picked. A normal build is exact at that size and wrong everywhere else: cramped at 1280, floating at 2560, off the bottom of a 700-tall laptop. fluid-design writes every drawn number as number × one unit, 1px at your frame, so the page is a proportional copy of the design at every window size.
runs onClaude CodeCodexCursorAntigravityopencodeGrok BuildHermesgeneratesTailwind v4CSSSCSSStyleXtested onNext.js
Tested on Next.js only, for now. Built and tuned on a production Next.js + Tailwind v4 site. The other stacks and frameworks generate correctly and pass the pack's tests, but no production site runs on them yet.
The dashed lines are the drawing's edges. It always fits: the unit follows the tighter axis, so a section drawn 900 tall is exactly one screen when height is the tighter one, and the composition keeps its proportions. (Backgrounds still run edge to edge; this is the drawn content.)
Your design is drawn at one size. People open it at every size.
Measured on the production marketing site this skill came from. Details: fluid-scale.md §1.
--fluid is 1px at your design frame (the artboard: the frame the designer
draws in) and grows and shrinks with the window, following whichever axis is tighter. Write every
drawn number times the unit and the whole page scales by one factor, keeping the design's
proportions. No clamp() pair per property to keep in sync.
svh
min() the tighter one wins: always fits
0.58 --fluid-desktop-scale-min
no ceiling --fluid-desktop-scale-max unset
1440 · 900 your frame, the default you can change
lg:fluid-py-120calc(120 * var(--fluid))fd.fluid(120)fluid(120)Divide the window's width by 1440 and its height by 900. The smaller number becomes
--fluid, so the design always fits. These are real fluid explain runs at
the default 1440×900 frame.
| window | width ÷ 1440 | height ÷ 900 | --fluid | a hero drawn 900 tall |
|---|---|---|---|---|
| 1440×900 | 1.0000 | 1.0000 | 1.0000 | 900px, exactly as drawn |
| 1280×800 | 0.8889 | 0.8889 | 0.8889 | 800px, fills the screen |
| 1440×700 | 1.0000 | 0.7778 | 0.7778 | 700px, fills the screen |
| 1024×900 | 0.7111 | 1.0000 | 0.7111 | 640px, shorter than the screen because the width is tighter |
| 1920×1080 | 1.3333 | 1.2000 | 1.2000 | 1080px, fills the screen |
| 2560×1440 | 1.7778 | 1.6000 | 1.6000 | 1440px, fills the screen |
dvh changes as the address bar slides away, so type would jump mid-scroll. svh holds still. Pinned layers use lvh, and so does the margin that offsets them.--fluid leaves the type units behind.64 * var(--fluid). With 64px the CSS is invalid and the browser drops the line without a warning.em letter-spacing and max line lengths keep their size. Corner radii grow with their box (fluid-rounded-*).fluid generate won't overwrite a file you edited by hand.The 1440 and 900 in the formula are the desktop frame your designer draws on in Figma, Sketch,
Penpot or any design app. Put that frame's size in your :root and the unit is 1px
there. Read every size off the design; the defaults are only fallbacks. A 1680×1050 desktop
frame works the same way, and a phone frame drawn 402 wide (iPhone 16 Pro) is 402, not 390.
| from the design file | setting in your :root | default |
|---|---|---|
| the desktop frame's width × height | --fluid-desktop-base-width / --fluid-desktop-base-height | 1440 × 900 |
| the content box's max width, side margins included | --fluid-desktop-container-width | 1680 |
| the side margin | --fluid-desktop-container-padding | 80 |
| the phone frame's width | --fluid-phone-base-width | 390 |
min(W / base-width, H / base-height).fluid init asks: Desktop design frame, width x height (1440x900).The base is your Figma frame, nothing else. “Base” just means the size of the desktop frame you measure from. Example: the
designer draws on a 1680×1050 frame, with a 48px heading. Set the base to 1680×1050,
type 48, and this is what the browser shows:
| browser window | the 48px heading renders at |
|---|---|
| 1440×900 | 41px smaller window, scaled down |
| 1512×982 14″ MacBook Pro | 43px |
| 1680×1050 same as the frame | 48px exactly as drawn |
| 1920×1080 | 49px capped by the height |
Forgot to set the base? It stays at the 1440×900 default, so a 1680 design comes out 17% too big at every window (the 48px heading is 56px on a 1680 screen).
Rare case: the designer put a 1440 layout in the middle of an extra-wide
1680 canvas. Measure the layout, not the canvas: base 1440×900, and
--fluid-desktop-container-width: 1680. That is what the defaults already are.
On desktop the unit also watches the window's height, so a section drawn 900 tall always fits one screen. One setting turns that off, and the page follows the width only. It applies live, like every setting. Try it with the follow the height switch in the demo.
| window (frame) | height on: 1, default | height off: 0 |
|---|---|---|
| 1440×700 (1440×900) | 0.78×, the 900-tall hero fits the screen | 1×, the hero is 900px and scrolls |
| 2000×1013 (1680×1050) | 0.96×, the page shrinks to the height and leaves side margins | 1.19×, the page fills the width |
| pick it for | sections drawn to fill one screen: a hero, a pinned scroll scene | pages where nothing has to fit one screen |
Phones, tablets and landscape always follow the width only. Height never squashes text: it scales the font size and the line height by the same number. If lines look cramped after a change, hard-reload first, because a stale stylesheet looks exactly like broken spacing.
The frame below is a small page drawn once at 1440×900 and once at 390, written only as
drawn number × unit through the pack's own generated fluid.css (the CSS stack at the
defaults, copied byte for byte). Pick a window, drag the corner, or switch off follow the height. The readout is measured inside
the frame, next to what fluid explain prints for the same window.
| variable | in the frame | fluid explain |
|---|---|---|
| multipliers | ||
| --fluid | 1.0000 | 1.0000 |
| --fluid-display | 1.0000 | 1.0000 |
| --fluid-copy | 1.0000 | 1.0000 |
| --fluid-ui | 1.0000 | 1.0000 |
| sizes, in px | ||
| --fluid-container-width | 1680.0 | 1680.0 |
| --fluid-container-padding | 80.0 | 80.0 |
| --fluid-header-h | 72.0 | 72.0 |
fluid explain column is what the CLI prints for the seven presets; it turns green where the frame agrees. At any other size only the live column updates.The demo's widest drawn row is 600 + 120 + 560 = 1280, and
fluid calc budget --widths 600,120,560 says PASS, 0px to spare inside the 80-padding
container. At 1440×700 the hero is 700px tall, at 2560×1440 it is 1440: the dashed dimension line
on its right edge always spans the window.
A band is a range of window sizes with its own design: phone, tablet, landscape (a phone
on its side) and desktop. Each has its own frame size, its own min and max for the unit, and its
own type damping. You write the phone numbers once for every mobile band and the desktop numbers
from lg: up; only the unit changes between bands. No redraw per breakpoint.
fluid-phone:| base width | 390 |
|---|---|
| unit min | 0.82 |
| unit max | 1.1 |
| display damping | 0.85 |
| copy damping | 0.6 |
| container | 560 |
| padding | 24 |
fluid-tablet:| base width | 700 |
|---|---|
| unit min | 1.1 |
| unit max | 1.3 |
| display damping | 0.85 |
| copy damping | 0.6 |
| container | 1024 |
| padding | 32 |
fluid-landscape:| base width | 780 |
|---|---|
| unit min | 1 |
| unit max | 1.2 |
| display damping | 0.85 |
| copy damping | 0.6 |
| container | 1024 |
| padding | 32 |
lg:min(W/1440, H/900) at the default.| base | 1440×900 |
|---|---|
| unit min | 0.58 |
| unit max | none |
| display damping | 0.62 |
| copy damping | 0.33 |
| container | 1680 |
| padding | 80 |
Every number above is a default you can set (--fluid-desktop-base-width, --fluid-tablet-scale-max, --fluid-phone-container-padding…),
and a default is a fallback for a band the design has no frame for. No tablet or landscape frame is the normal case:
the container width defaults to the desktop breakpoint (wider than any window in those bands), so the phone design runs full
width with a 32 gutter instead of floating in a phone-sized column. Want the old 560 column? Set
--fluid-tablet-container-width: 560 and --fluid-tablet-container-padding: 24 (same for landscape).
Keep --fluid-tablet-scale-min equal to --fluid-phone-scale-max so nothing jumps at 600.
The band variants are exclusive, and never mix one with sm:/md: on a property: band variants sort after
every breakpoint, so they always win. Have a separately authored mobile layout? bands.phone: false
(or fluid init --no-mobile) keeps a flat 1px below desktop.
A heading shares its column with fixed measures, so type should shrink more gently than the
layout. A type role is a size curve for that: --fluid-display for headlines,
--fluid-copy for body and labels, plus any role you add (caption).
Damping is how much a role shrinks with the layout: 1 shrinks as much as the layout, 0 never
goes below its drawn size. Above the design frame, roles grow with the unit one to one. Plotted
from the engine's formula at the desktop defaults:
--fluid-display = max(--fluid, d · max(--fluid, knee) + (1 − d)), where
d is the damping and the knee is the unit at the desktop breakpoint (1024 / 1440 = 0.711 with the default
frame). Below it, type holds its size: on a short desktop window the layout keeps shrinking toward 0.58 so the
section still fits, while headings stay readable.
| the text sits in… | use | why |
|---|---|---|
| a fixed column beside fixed measures | fluid-display-* | damped: shrinks less than the layout, so the line count holds |
| a box that scales with the layout (a card, a figure) | fluid-text-* | the base unit, blended toward the zoomed one for browser zoom |
| small labels and controls | fluid-copy-* | damped harder (0.33): barely shrinks at all |
| the header, nav and footer | fluid-ui-* | follows the width, never shrinks for a short window |
| a button, chip or icon around a label | fluid-copy-h-56 fluid-copy-px-24 | the box uses the label's role, so the two keep their proportion. Every role has -h -w -size -p -px -py -gap |
--fluid-header-h is built from it.--fluid-z, so text still zooms 1:1 while the layout keeps fitting.<FluidHead />, Vite fluidPlugin(), or zoom.classic.js. Under a strict CSP pass a nonce, or allow FLUID_ZOOM_SHA256.Sometimes part of a page should stop scaling: a header that stops growing past a 1680 window,
a panel that never shrinks below its 1280 size, a widget that should not scale at all. That is a
limit: one utility on the element, in window px. It makes the element a scope (part of
the page with its own settings), and every fluid-* class inside follows. On a tall
window, where width is the tighter axis:
--fluid-grow-until: 1680.--fluid-ui stops growing. For the site header, set it on :root so --fluid-header-h holds with it.fluid-off beats a limit on the same element, and lg:fluid-grow-until-1680 limits only from lg. A limit applies only in the band that contains its width.class="fluid-scope" (or data-fluid-scope) plus a setting gives one section a different container, damping or scale-min. Every unit recomputes together there.fluid explain --url lists every limited subtree on a live page with what inside follows the scale, and flags a limit with nothing fluid inside.<header> drifts from --fluid-header-h on :root. Use :root { --fluid-ui-grow-until: 1680 }; fluid check warns on the class.viewport-fit=cover keeps content clear of the notch with no extra rules.fluid-bleed-x inside it reaches the window's edges and pads back in, so a carousel track runs edge to edge while its content lines up with the container.--fluid-desktop-container-padding: 108 widens every section at once.cqw, or a fixed drawn max width). A smaller padding never fixes it.There are two places to configure, and every option lives in exactly one of them. You
never set the same thing twice. Most changes are numbers, and numbers go in your CSS
:root only: the JSON file is not touched and nothing has to run.
| you want to change | edit | then |
|---|---|---|
| frame sizes, gutters, container width, how far the scale shrinks or grows, type damping, limits, height on or off | :root in your CSS | nothing, it applies live |
| where a band starts (the tablet or desktop breakpoint), or turning a band on or off | fluid.config.json | fluid generate |
adding a type role ("caption"), the ui or zoom unit on or off, Tailwind options, the class prefix, the stack or output folder | fluid.config.json | fluid generate |
The JSON decides which CSS rules exist, so changing it means
regenerating. The :root variables are the numbers inside those rules. Here is what
fluid init wrote for a Next + Tailwind v4 project:
"caption"), the prefix, ui and zoom on or off, the output stack and folder.output.editor: true also writes the VS Code settings autocomplete and a settings.reference.css.fluid check flags a typo with a suggestion. fluid settings lists them all.One import brings the units, the settings, the base layer, the breakpoints, the band variants and the utilities.
Everything is generated into one folder (src/styles/fluid/ by default): fluid.css, base.css,
fluid.ts, cn.ts / _index.scss / fluid.stylex.ts,
runtime/, integrations/ and a plain-words README.md. The decisions are logged in a short FLUID.md.
Every key and setting with its default: config.md.
The skill drives one CLI, and so can you. A real session in a fresh Next + Tailwind v4 project, then a live check of this page's own demo frame (served locally, checked from a CSS-stack project, the stack the frame uses):
| command | what it does |
|---|---|
| init | asks the design questions (or takes flags), writes the config, generates, wires the import, your settings and the fluid npm script |
| generate [--watch] | writes the output folder from the config; refuses to overwrite a hand edit; CRLF- and formatter-safe |
| check | the CI gate: config, generated files, settings lint, source rules |
| settings [--json] | every setting with its default (what you can put in your :root) |
| explain WxH | every unit at a viewport and where it came from; --url for the live page, its verdict and every scope |
| probe <url> | a one-shot freshness verdict |
| migrate [--write] | moves a v1 config to v2 |
| calc · verify · audit | maths tables and the content budget · the Playwright viewport matrix with a real browser-zoom row · the static source audit |
Every stack spends the same custom properties, defined once in the generated fluid.css;
only the authoring surface differs. The same hero, four spellings:
The phone number unprefixed, the desktop one behind lg:. Bare numbers in 0.25 steps, anything else bracketed (fluid-p-[8.3]); /lh is drawn px, not a ratio. The button's box reads the same role as its label, so the two scale together. Components that take className need a cn that knows the fluid classes: keep yours and extend it with withFluid.
Plain var() inside each band's media query, plus one class, .fluid-container. CSS Modules is the same stack. Classic min-width syntax keeps your own queries at the Safari 15.4 floor.
Functions (fd.fluid(), fd.fluid-display(), fd.fluid-copy(), fd.fluid-ui()…) that work on any property, exclusive band mixins and fd.fluid-bleed-x, on top of the same fluid.css. The functions @error on a number that already has a unit, so the silent 64px * var(--fluid) failure becomes a build error.
Typed helpers that return calc() strings, plus fluidContainer as a style object. The units stay plain global CSS: StyleX's defineVars cannot express a variable whose formula reads a sibling, which every unit does. The media key is DESKTOP_QUERY from fluid.ts.
| what you get | Tailwind v4 | CSS | SCSS | StyleX |
|---|---|---|---|---|
the units, settings and fluid-container | ✓ | ✓ | ✓ | ✓ |
fluid-* utilities for every spacing, size and type family, and box sizes on each type role | ✓ | — | —functions | —helpers |
fluid-bleed-x: an edge-to-edge strip aligned with the container | ✓ | ✓class | ✓mixin | ✓class |
band variants fluid-phone: fluid-tablet: fluid-landscape: | ✓ | — | ✓mixins | — |
class merging (cn.ts, withFluid) + IntelliSense | ✓ | — | — | — |
a build error on 64px * unit | — | — | ✓ | ✓typed |
fluid.ts: DESKTOP_QUERY, MEDIA, fluidPx() for motion code | ✓ | ✓ | ✓ | ✓ |
| tested on a production site | ✓Next.js | —tests only | —tests only | —tests only |
| browser floor | Tailwind v4's own | Safari 15.4 · Chrome 108 · Firefox 101 | ||
fluidPx(n, unit, el) turns a drawn number into CSS px at an element, limits included, for GSAP or Motion
distances. Tailwind 3 cannot run functional utilities: fluid init picks the CSS stack and recommends the upgrade.
The engine is plain CSS, so it is tested in real browsers against an independent JS model of the maths, not by reading the stylesheet. The numbers below come from the repository's suites, re-run for this page:
tests/engine-matrix.mjs)tests/scss-browser.mjs)tests/resize-perf.mjs)And in your project, the same gates the skill runs before it calls the work done:
dvh on scaled boxes, a limit on children, a /1.5 line-height ratio.--browser webkit and --browser firefox.lvh shortfall and safe areas can only be verified on a phone. The skill reports this gate as open rather than claiming it.The skill triggers on what people say, even without the word "fluid". Its
SKILL.md is a router: preflight first, then only the references the task touches.
clamp()/vw/svh sizingtypography.md
"Convert this Tailwind site to fluid scaling"brownfield-migration.md
iOS Safari viewport bugs, the toolbar tintios-safari.md
Broken after a CSS edit and a dev-server restartverification.md §6
All eighteen, grouped by when you need them:
preflight.mdalways first: stack, design frames, bands, container, roles, ceiling, zoom, each with a default and a detection hint
config.mdgenerated: every structure key and setting with its default
fluid-scale.mdthe base unit: drawn number × unit, the two axes, the design frame, the ceiling
units.mdtype roles and damping, the ui unit, the header height, the container units
bands.mdphone, tablet, landscape, desktop: switches, continuity, full width
limits-and-scopes.mdone scale per page; limits and scopes
browser-zoom.mdWCAG 1.4.4: the head script, CSP, detection, the handover
contract.mdthe checked vocabulary: browser floor, utilities, fluid.ts exports, what motion code reads
section-recipe.mdthe per-section checklist and shipped anatomy
frame-and-gutter.mdone container per section, the content budget, cqw escapes
typography.mdthe type unit per text element, /lh, em tracking, fonts
media.mdimages, inline SVG and <video> sized and reserved in fluid units
tokens-and-theming.mdwhere tokens live beside the settings, and the traps that compile clean
stacks.mdTailwind v4, CSS and CSS Modules, SCSS, StyleX
brownfield-migration.mdfluid migrate, route-by-route conversion, keeping an existing cn
ios-safari.mdsvh/lvh/dvh, safe areas, the iOS 26 toolbar tint, sticky killers
performance.mdthe render budget: resize cost, image sizes on a page that grows, fonts
verification.mdthe tiers, the viewport matrix cell by cell, the stale-stylesheet diagnosis
Three ways in, one CLI. An agent runs it for you; a developer can run it by hand, with or without Node.
node <skill>/bin/fluid itself.init detects your stack and framework and asks the design questions.fluid binary for Phoenix, plain HTML and anything else. Windows: install-cli.ps1.The same install runs on any Agent Skills
host. Codex installs to ${CODEX_HOME:-$HOME/.codex}/skills; agents
remains a separate cross-agent target. If a project already uses one of the three channels,
the skill uses it instead of installing a second.
| host | install target | command |
|---|---|---|
| Claude Code | ~/.claude/skills | ./install.sh claude |
| Codex | ${CODEX_HOME:-$HOME/.codex}/skills | ./install.sh codex |
| Cross-agent path | ~/.agents/skills | ./install.sh agents |
| Cursor CLI | ~/.cursor/skills | ./install.sh cursor |
| Antigravity (IDE + agy) | ~/.gemini/…/skills | ./install.sh antigravity |
| opencode | ~/.config/opencode/skills | ./install.sh opencode |
| Grok Build | ~/.grok/skills | ./install.sh grok |
| Hermes | ~/.hermes/skills | ./install.sh hermes |
Prefer npx skills add gabros20/fluid-design-skill when you have Node: it maps supported clients itself.
More docs: docs/installation.md · docs/usage.md · docs/recipes.md.
This skill makes the page the right size. It contains no animation. So far it runs in production on Next.js + Tailwind v4 only; other setups pass the tests but have no live site behind them yet.
clamp() type (Utopia-style "make it responsive"): a different model, one pair per property.