Skip to Content
inkblot

🎨 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

PropertyPurpose
--inkblot-colourThe ink colour. Set for you from the colour option.
--inkblot-durationAnimation length. Set for you from the mode or the duration option.
--inkblot-zThe 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.

  • true forces the fade, for example from an in-app accessibility switch.
  • false forces 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.