@jordandavila/fluid-canvas weekly downloads statistics

@jordandavila/fluid-canvas

Proportional canvas design system for Tailwind CSS. Author every measurement in design px straight from the Figma frame; the composition scales like a poster. One package, two builds — a Tailwind v3 plugin and a Tailwind v4 CSS-first build — kept identical by a parity check that runs on every release.

--uw: calc(min(100cqi, 2560px) / 1920);  /* one design px, WIDTH canvas  */
--uh: calc(100svh / 1080);               /* one design px, HEIGHT canvas */

p-u-24 is exactly 24px at the 1920 frame and proportional everywhere else. No clamp ramps, no per-breakpoint overrides.

Type roles split into a fixed rem part and a scaling part, which is what keeps browser zoom working (measured 1.75× growth on body at 200%, where a purely viewport-derived size grows not at all) and collapses the breakpoint seam to +0.2% on h1. The width canvas reads cqi, so a component inside a container-type: inline-size ancestor scales to that ancestor, not the window.

---

Install

npm install @jordandavila/fluid-canvas

tailwindcss is a peer dependency: ^3.4.0 || ^4.0.0.

Tailwind v4 — CSS only

/* app.css */
@import 'tailwindcss';
@import '@jordandavila/fluid-canvas';

Tailwind v3 — plugin

// tailwind.config.ts
import fluid, { defaultPreset } from '@jordandavila/fluid-canvas/v3'

export default {
  content: ['./src/**/*.{ts,tsx,njk,html}'],
  plugins: [fluid(defaultPreset)],
}

// tailwind.config.js (CommonJS) — use the named export, not `.default`
const { fluid, defaultPreset } = require('@jordandavila/fluid-canvas/v3')

Either way you get the same class names:

<section class="py-section">
  <div class="ui-container flex flex-col gap-u-24">
    <h1 class="text-h1">Poster scale</h1>
    <p class="text-body max-w-measure">Design px in, proportional px out.</p>
  </div>
</section>

---

Entry points

Import	Build	Notes
@jordandavila/fluid-canvas	v4 CSS	the default — v4 is CSS-first, so this is a stylesheet
@jordandavila/fluid-canvas/v4	v4 CSS	explicit alias of the above
@jordandavila/fluid-canvas/v4/canvas.css	v4 CSS	engine only, bring your own tokens
@jordandavila/fluid-canvas/v4/tokens.css	v4 CSS	tokens only
@jordandavila/fluid-canvas/v4/utilities/*.css	v4 CSS	individual utility groups
@jordandavila/fluid-canvas/v3	JS plugin	dual ESM + CJS, typed
@jordandavila/fluid-canvas/runtime/text-scale	JS	--ui-text-scale control, shared by both

The root export is a stylesheet, not JavaScript. import x from '@jordandavila/fluid-canvas' in a Node script will not do what you want — v3 users always go through /v3.

---

Demos

Two runnable demos rendering identical markup, one per Tailwind major — a live instrument panel, a type specimen that lights up each rem floor as it engages, and the text-size control wired to the shipped runtime.

npm install && npm run build
cd demos/v3 && npm install && npm start   # serves /v3/ and /v4/ on :5173

See demos/README.md.

---

Documentation

• v3 guide — plugin options, presets, the bare-value map
• v4 guide — file map, @theme tokens, composing partials

Both cover the type-scale modes, the floor table, the full utility surface, and the accessibility story. Start with whichever Tailwind you are on.

---

Why one package for two Tailwind majors

The alternative is two packages (-v3 / -v4 suffixes) or two release lines on different majors. Both were rejected:

• A suffix reads like the package's own version. fluid-canvas-v3@2.1.0 is a genuinely confusing string.
• Two release lines mean backporting every fix, and nothing mechanically guarantees the two stay in sync.

Shipping both from one tree makes the parity guarantee real: prepublishOnly compiles the same fixture through Tailwind v3 and Tailwind v4 and refuses to publish unless every class rule and every token variable resolves identically. The cost is a few unused KB in node_modules for whichever build you skip.

Versioning

The package version tracks this system, not Tailwind. 1.x supports Tailwind 3.4+ and 4.x simultaneously. Dropping a Tailwind major is a breaking change and would be a major bump here — it will not be signalled by the package name.

Relationship to @jordandavila/tailwind-fluid

Separate package, separate system. That one scales against a per-breakpoint Figma frame and uses *-fluid-* class names; this one is a poster model with *-u-* / *-uh-* names. Neither replaces the other and no migration is implied.

---

Development

npm install
npm test          # build → compile both fixtures → parity check
npm run build     # tsup: v3/dist ESM + CJS + types
npm run typecheck
npm run release:dry

The v4 fixture lives in test/v4 with its own node_modules. That is deliberate: Tailwind 3 and Tailwind 4 both provide a tailwindcss binary, so they cannot share one install without a bin collision. The root install pins Tailwind 3 (it is also the type source for the plugin) and test/v4 nests Tailwind 4.

Publishing

npm login
npm publish            # prepublishOnly runs typecheck + full parity test

The package is scoped, so publishConfig.access is set to public — without it npm would attempt a restricted (paid) publish.

License

ISC © Jordan Davila