π¨ Styling
Custom properties, the injected stylesheet, strict CSP setups and reduced-motion behaviour.
Inkblot ships no CSS framework and no dependency. Every class is namespaced inkblot-*, so a Tailwind site and a plain one behave identically and neither stylesheet leaks into the other.
Custom properties
| Property | Purpose |
|---|---|
--inkblot-colour | The ink colour. Set for you from the colour option. |
--inkblot-duration | Animation length. Set for you from the mode or the duration option. |
--inkblot-z | The overlay's z-index. Defaults to 2147483646; set it yourself. |
#overlay {
--inkblot-z: 50;
}The overlay element
Inkblot fixes the overlay to the viewport, oversized by 60 px on every side (inset: -60px), so the displacement never bares a screen edge. It adjusts the origin for that offset, so from is always in plain viewport coordinates. The overlay has pointer-events: none.
Injection
By default the stylesheet (about 2 KB) is injected once from JS, along with the SVG filter, on the first spill(). A bundler-specific stylesheet import is not portable between a Next.js app and a plain Vite or no-bundler site; a <style> tag injected from the module works the same in both, with no config.
Strict CSP
Under a policy that forbids inline <style>, load the stylesheet yourself and skip the injection:
import "@kud/inkblot/style.css"
import { spill } from "@kud/inkblot/core"
await spill(overlay, { mode: "cover" })The /core entry skips the stylesheet injector entirely, so its JavaScript does not carry the stylesheet string. The default entry keeps inject: false for compatibility but still bundles those stylesheet bytes. The @kud/inkblot/style.css import is retained by bundlers using the package's CSS-only side-effect declaration.
The filter is still added to the page as an inline SVG element, which a style-src policy does not restrict.
Reduced motion
With prefers-reduced-motion: reduce, every mode becomes a plain fade with no spreading edge: 280 ms in, 400 ms out, and 280 ms for the veil. An explicit duration still applies.
A per-call reducedMotion option overrides the media query. Leaving it out, so every call follows the operating system, is the recommended path.
trueforces the fade, for example from an in-app accessibility switch.falseforces the spreading ink even when the operating system asks for reduced motion. Use it only behind an explicit in-app opt-in the user chose themselves, or on preview and documentation pages that demonstrate the effect. Never make it a default, and never pass it to ship full motion because it looks nicer.
Debug time scale
Use setTimeScale(4) to slow all subsequent transitions to a quarter of their normal speed, including reduced-motion fades and explicit duration values. setTimeScale(0.5) speeds them up, and setTimeScale(1) resets the global multiplier. The same factor applies to the animation's safety timeout so a slowed spill does not resolve prematurely.