Documentation
- 311 sections
- Solid
- Tailwind or StyleX
Quick start
The kit is a folder, not a package. Copy dither-kit/ from the GitHub repo (opens in a new tab), install four small runtime deps and alias it. You already have Solid, and Tailwind if you use it.
Copy the kit folder straight from the repo
degit grabs just the folder
npx degit drvova/dither-ui/packages/dither-kit/src src/dither-kitInstall the runtime deps
you already have Solid, and Tailwind if you use it
npm i d3-scale d3-shape clsx tailwind-mergeAlias @dither-kit so imports stay clean
// vite.config.ts resolve: { alias: { "@dither-kit": "/src/dither-kit/solid" } } // tsconfig.json, under compilerOptions "paths": { "@dither-kit": ["./src/dither-kit/solid"] }Use it
import { AreaChart, Area, DitherButton } from "@dither-kit"
Without Tailwind
The kit brings its own stylesheet, in cascade layers so your styles win. Pick your system in the header and every snippet here, every Studio export and the agent's code.get come out as a scoped stylesheet, CSS Modules or StyleX.
<!-- No Tailwind? One plain stylesheet: the tokens, a base scoped to
.dither-kit and every class the components use. -->
<link rel="stylesheet" href="https://dither-ui.com/kit/dither-kit.css">
<div class="dither-kit">
<DitherButton class="cta">Ship</DitherButton>
</div>The tokens are plain custom properties, so theme from CSS, JS or any vars contract:
import { applyTheme, themeCss } from "@dither-kit"
applyTheme({ accent: "#3f8ff3", radius: "4px" }) // on <html>, returns the undo
themeCss({ background: "#000" }, ".dark") // a rule for your stylesheetPrefer to read the source first? Every component lives under dither-kit/ (opens in a new tab). No build step, no black box.
Engine
The parts under every surface, each named once: what it does in one line, and a figure read from the kit's own source.
- Matrix
- Each cell compares its tone with one rank of a 4×4 threshold matrix and lights when the tone passes it, so a flat fill becomes a pattern of lit and unlit cells. Print screens
- 16 ranks, 17 tones
- Screens
- The matrix is Bayer's unless a DitherScreen around a surface picks a printer's line, diagonal, dot or cross; a fill that carries a label keeps Bayer, so its letters hold. Print screens
- 5 screens
- Seeds
- One integer seeds the matrix's jitter, the texture, the bloom and the easing, so the same seed draws the same surface every time. Seeds
- 1 integer
- Palette
- One table resolves each hue to the fill, line and star colours every surface paints with, and the theme's swatches mirror it. Palette
- 7 hues
- Clock
- One clock drives every animation; held at a moment, every surface paints that moment, and the same moment gives the same bytes. Stage
- 0 frames while held
- Wipe
- Reveals and page transitions are ordered-dither masks: a cell shows once the sweep passes its rank in an 8×8 matrix, so a wipe has a dithered front, never a soft edge. Dither reveal
- 64 ranks
- World
- Model files parse in the page and rasterize on the CPU byte for byte, or on WebGL for big meshes, into the same dither pass. World (3D)
- 8 formats
- Shader
- GLSL compiles offscreen at the cell resolution and its pixels are read back and dithered; iTime is the kit's clock, and other surfaces bind as its inputs. Shader (GLSL)
- 4 inputs
Verification
The kit's claims, measured with its own engine in the browser reading this page: what each one claims, how it is measured and against what, then the reading. CI takes the same readings on every push, and each claim links the test that holds it.
Measured in your browser when this section comes into view.
- Same seed, same moment, same bytes
- The poster is printed twice at seed 5 and 2.4 s and every byte compared; printed again at 3.4 s, the control must differ. Its test: Same seed, same moment, same bytes (opens in a new tab)
- not yet measured
- against 0 bytes differ
- The same bytes in every engine
- The same print is hashed through the kit's FNV-1a and set beside the hash CI recorded running the kit in Node. Its test: The same bytes in every engine (opens in a new tab)
- not yet measured
- against hash c8364f4f
- Every screen prints 17 tones
- Each screen's 4×4 thresholds are set against 17 even tone steps by the rule every surface prints with, a cell lighting when the tone passes its threshold, and the lit cells counted. Its test: Every screen prints 17 tones (opens in a new tab)
- not yet measured
- against step k lights k cells
- The 3D engine repeats itself byte for byte
- A box read from a VRML file is rasterized twice on the CPU at one view and every byte compared; turned 15°, the control must differ. Its test: The 3D engine repeats itself byte for byte (opens in a new tab)
- not yet measured
- against 0 bytes differ
- A scene scales exactly with its box
- A track of container units and percentages is sampled at 0.7 s and resolved in a 320 by 180 box, then in one twice that size. Its test: A scene scales exactly with its box (opens in a new tab)
- not yet measured
- against every length doubles
- A wipe shows one more cell per step
- The dissolve's mask is drawn at each of the 64 steps of its 8×8 matrix and its shown cells compared step to step. Its test: A wipe shows one more cell per step (opens in a new tab)
- not yet measured
- against one more each step
- 8 model formats read in the page
- A triangle written in each format (a Gaussian in the capture's) is parsed by the kit's own readers, here, with nothing fetched. Its test: 8 model formats read in the page (opens in a new tab)
- not yet measured
- against a triangle or a Gaussian from each
- The landing's inks hold their contrast as printed
- Bone, muted bone and the ember are printed through the Bayer matrix on the obsidian at full and half tone, and each patch is measured from its pixels in linear light. Its test: The landing's inks hold their contrast as printed (opens in a new tab)
- not yet measured
- against 4.5:1 full, 3:1 at half
Animated content
Wrap anything to have it slide and fade into place the first time it enters the viewport. Direction, distance and timing are configurable, and distance takes CSS lengths too: distance="4cqw" reveals from 4% of the nearest query container, so the motion measures its parent instead of pixels.
- distance
- Typenumber (px) | CSS length: "4cqw" rides the nearest query container Default40
- direction
- Type"vertical" | "horizontal" Default"vertical"
- reverse
- Typeboolean Defaultfalse
- duration
- Typenumber (ms) Default800
- delay
- Typenumber (ms) Default0
- children
- Typecontent Defaultnone
Fade content
A pure fade-in on view, optionally de-blurring as it appears. The lighter cousin of Animated content when you only want opacity.
- duration
- Typenumber (ms) Default1000
- delay
- Typenumber (ms) Default0
- blur
- Typeboolean Defaultfalse
- children
- Typecontent Defaultnone
Gradual blur
A masked backdrop-filter strip that progressively blurs toward an edge: the iOS-style soft fade over a scroll region.
- position
- Type"bottom" | "top" Default"bottom"
- height
- Typenumber (px) Default96
- strength
- Typenumber (px) Default4
- children
- Typecontent Defaultnone
Star border
A rounded frame with two bright glints traveling its top and bottom edges: a subtle animated outline for a CTA or badge.
- color
- Typestring (hex) Default"#7CFF67"
- speed
- Typenumber (s) Default6
- thickness
- Typenumber (px) Default1
- children
- Typecontent Defaultnone
Electric border
An SVG turbulence filter jitters the frame edge into a crackling electric outline. Reduced motion drops the displacement.
- color
- Typestring (hex) Default"#5227FF"
- speed
- Typenumber Default1
- thickness
- Typenumber (px) Default2
- children
- Typecontent Defaultnone
Glare hover
A diagonal sheen sweeps across the surface on hover: the glossy-card reflection, done with a single masked gradient. Hover the card.
- children
- Typecontent Defaultnone
Magnet
The wrapped element is pulled toward the pointer while it is within range, easing back when the cursor leaves. Move your cursor near the button.
- strength
- Typenumber (0-1) Default0.4
- radius
- Typenumber (px) Default200
- children
- Typecontent Defaultnone
Click spark
A burst of spark lines radiates from every click inside the area, drawn on a lightweight canvas overlay. Click anywhere in the preview.
- color
- Typestring (hex) Default"#7CFF67"
- count
- Typenumber Default8
- size
- Typenumber (px) Default16
- duration
- Typenumber (ms) Default420
- children
- Typecontent Defaultnone
Blob cursor
A soft, screen-blended blob eases toward the pointer inside the area: a gooey cursor companion. Move your cursor over the box.
- color
- Typestring (hex) Default"#7CFF67"
- size
- Typenumber (px) Default48
- lag
- Typenumber (0-1) Default0.18
- children
- Typecontent Defaultnone
Crosshair
Full-height and full-width guide lines track the pointer across the area: a precision reticle. Move your cursor over the box.
- color
- Typestring (hex) Default"#7CFF67"
- thickness
- Typenumber (px) Default1
- children
- Typecontent Defaultnone
Ghost cursor
A tapering trail of fading dots chases the pointer on a canvas overlay. Move your cursor over the box.
- color
- Typestring (hex) Default"#7CFF67"
- count
- Typenumber Default18
- size
- Typenumber (px) Default10
- children
- Typecontent Defaultnone
Splash cursor
Expanding ripple rings bloom along the pointer path, like drops on water. Move your cursor over the box.
- color
- Typestring (hex) Default"#3DA5FF"
- maxRadius
- Typenumber (px) Default60
- duration
- Typenumber (ms) Default700
- children
- Typecontent Defaultnone
Target cursor
A slowly rotating corner-bracket reticle locks onto the pointer: a HUD targeting frame. Move your cursor over the box.
- color
- Typestring (hex) Default"#7CFF67"
- size
- Typenumber (px) Default36
- children
- Typecontent Defaultnone
Pixel trail
The pointer lights up cells of a pixel grid that then fade back out: a glowing wake across the lattice. Move your cursor over the box.
- color
- Typestring (hex) Default"#7CFF67"
- gap
- Typenumber (px) Default24
- children
- Typecontent Defaultnone
Image trail
Tiles from a palette drop along the pointer path, rotating and shrinking as they fade. Pass real image URLs via colors swapped for tiles here. Move your cursor over the box.
- colors
- Typestring[] (hex) Default['#5227FF', '#7CFF67', ...]
- size
- Typenumber (px) Default40
- duration
- Typenumber (ms) Default650
- children
- Typecontent Defaultnone
Meta balls
Orbiting blobs fuse into a gooey metaball iso-surface, tinted and ordered-dithered through the kit engine. The pointer adds a blob.
- colors
- Typestring[] (hex) Default['#5227FF', '#7CFF67', '#3DA5FF']
- count
- Typenumber Default6
- speed
- Typenumber Default1
- ballSize
- Typenumber Default1
- glow
- Typenumber Default1.5
- mouseInteraction
- Typeboolean Defaulttrue
- opacity
- Typenumber (0-1) Default1
- dither
- Typenumber (0-1) | boolean Default1
- paused
- Typeboolean Defaultfalse
- mixBlendMode
- Typestring Defaultundefined
- seed
- Typenumber Defaultundefined
- frameRate
- Typenumber (fps, stop-motion) Default0 (smooth)
Metallic paint
Iterative domain-warped reflections read as flowing liquid chrome. Fully opaque, dithered across a metallic ramp.
- colors
- Typestring[] (hex) Default['#1A1A22', '#8890A0', '#E8ECF4']
- scale
- Typenumber Default3
- speed
- Typenumber Default0.4
- distortion
- Typenumber Default0.6
- opacity
- Typenumber (0-1) Default1
- dither
- Typenumber (0-1) | boolean Default1
- paused
- Typeboolean Defaultfalse
- mixBlendMode
- Typestring Defaultundefined
- seed
- Typenumber Defaultundefined
- frameRate
- Typenumber (fps, stop-motion) Default0 (smooth)
Noise
Animated hashed grain thresholded against the Bayer matrix: living static for a texture overlay. Tune density and blend it over content.
- colors
- Typestring[] (hex) Default['#3DA5FF', '#7CE0FF', '#FFFFFF']
- speed
- Typenumber Default1
- density
- Typenumber (0-1) Default0.5
- opacity
- Typenumber (0-1) Default1
- paused
- Typeboolean Defaultfalse
- frameRate
- Typenumber (fps, stop-motion) Default0 (smooth)
Cubes
A rhombille tiling shades into a field of isometric cubes, each face lit and pulsing on noise. Tinted and ordered-dithered.
- colors
- Typestring[] (hex) Default['#5227FF', '#7CFF67', '#CFFFDF']
- scale
- Typenumber Default6
- speed
- Typenumber Default0.4
- opacity
- Typenumber (0-1) Default1
- dither
- Typenumber (0-1) | boolean Default1
- paused
- Typeboolean Defaultfalse
- mixBlendMode
- Typestring Defaultundefined
- seed
- Typenumber Defaultundefined
- frameRate
- Typenumber (fps, stop-motion) Default0 (smooth)
Ribbons
Thick flowing bands ride wavy fbm centerlines, bright at the core and tinted per ribbon. The pointer bends nearby ribbons toward it.
- colors
- Typestring[] (hex) Default['#5227FF', '#7CFF67', '#3DA5FF']
- count
- Typenumber Default5
- thickness
- Typenumber Default0.12
- amplitude
- Typenumber Default1
- mouseInteraction
- Typeboolean Defaulttrue
- opacity
- Typenumber (0-1) Default1
- dither
- Typenumber (0-1) | boolean Default1
- paused
- Typeboolean Defaultfalse
- mixBlendMode
- Typestring Defaultundefined
- seed
- Typenumber Defaultundefined
- frameRate
- Typenumber (fps, stop-motion) Default0 (smooth)
Shape blur
A big soft blob morphs on noise and drifts toward the pointer: a gentle out-of-focus shape. Move your cursor over it.
- colors
- Typestring[] (hex) Default['#5227FF', '#7CFF67']
- size
- Typenumber Default0.4
- softness
- Typenumber Default0.3
- mouseInteraction
- Typeboolean Defaulttrue
- opacity
- Typenumber (0-1) Default1
- dither
- Typenumber (0-1) | boolean Default1
- paused
- Typeboolean Defaultfalse
- mixBlendMode
- Typestring Defaultundefined
- seed
- Typenumber Defaultundefined
- frameRate
- Typenumber (fps, stop-motion) Default0 (smooth)
Strands
Dozens of thin filaments sway on fbm like blown hair, tinted by depth and ordered-dithered with transparent gaps.
- colors
- Typestring[] (hex) Default['#5227FF', '#7CE0FF']
- count
- Typenumber Default40
- sway
- Typenumber Default0.15
- lineWidth
- Typenumber Default0.01
- opacity
- Typenumber (0-1) Default1
- dither
- Typenumber (0-1) | boolean Default1
- paused
- Typeboolean Defaultfalse
- mixBlendMode
- Typestring Defaultundefined
- seed
- Typenumber Defaultundefined
- frameRate
- Typenumber (fps, stop-motion) Default0 (smooth)
Laser flow
Sharp horizontal beams sweep with additive bloom and a faint jitter, tinted per beam: a scanning laser array.
- colors
- Typestring[] (hex) Default['#FF3D2E', '#FFD23D', '#FFFFFF']
- count
- Typenumber Default4
- beamWidth
- Typenumber Default0.02
- glow
- Typenumber Default1
- opacity
- Typenumber (0-1) Default1
- dither
- Typenumber (0-1) | boolean Default1
- paused
- Typeboolean Defaultfalse
- mixBlendMode
- Typestring Defaultundefined
- seed
- Typenumber Defaultundefined
- frameRate
- Typenumber (fps, stop-motion) Default0 (smooth)
Antigravity
A field of motes drifts upward and wraps: gravity in reverse, layered behind your content.
- color
- Typestring (hex) Default"#7CFF67"
- count
- Typenumber Default40
- speed
- Typenumber Default1
- children
- Typecontent Defaultnone
Logo loop
A seamless infinite marquee of items. Pass logos or wordmarks and it loops forever with a measured wrap.
- items
- Typestring[] Default['DITHER', 'BAYER', ...]
- speed
- Typenumber (s) Default18
- gap
- Typenumber (px) Default48
Magic rings
Concentric rings pulse outward from the center on a stagger: a radar-ping halo around whatever you wrap.
- color
- Typestring (hex) Default"#7CFF67"
- count
- Typenumber Default4
- duration
- Typenumber (s) Default3
- children
- Typecontent Defaultnone
Magnet lines
A grid of little needles all swivel to point at the pointer, like iron filings over a magnet. Move your cursor over the box.
- color
- Typestring (hex) Default"#7CFF67"
- gap
- Typenumber (px) Default28
- lineLength
- Typenumber (px) Default14
- children
- Typecontent Defaultnone
Orbit images
Items ride a circular orbit around a center point. Pass avatars, logos or labels. Counter-rotated so they stay upright.
- items
- Typestring[] Default['A', 'B', 'C', 'D', 'E']
- radius
- Typenumber (px) Default80
- duration
- Typenumber (s) Default16
- size
- Typenumber (px) Default200
Pixel transition
A grid of pixel cells covers the content and dissolves in a scattered order on hover, revealing what is underneath. Hover the card.
- rows
- Typenumber Default6
- cols
- Typenumber Default10
- color
- Typestring (hex) Default"#111318"
- children
- Typecontent Defaultnone
Dither reveal
Any content comes in through an ordered-dither mask. A dissolve resolves cell by cell in the Bayer order; a wipe moves a solid front with a dithered band behind it. The mask is a pure function of progress, so a seeked frame (the player, a video export) gets the same cells every time, and the Studio's reels cut between frames with it. Pass progress to drive it from your own timeline.
- progress
- Typenumber 0–1 (manual; unset plays on the clock) Defaultnone
- duration
- Typenumber (s) Default1.2
- delay
- Typenumber (s) Default0
- direction
- Type'none' | 'right' | 'left' | 'down' | 'up' | 'iris' Default'none' (dissolve)
- cell
- Typenumber (px) Default4
- band
- Typenumber (cells; directional wipes) Default12
- seed
- Typenumber (a seeded 4×4 matrix) Defaultnone (Bayer 8×8)
- reverse
- Typeboolean (hide instead) Defaultfalse
- easing
- TypeEasingInput Default'ease-in-out'
- restartKey
- Typeunknown (change to replay) Defaultnone
- children
- Typecontent Defaultnone
Page transition
One state turns into the next through the same masks. ditherTransition runs any DOM change as a view transition and dithers its two snapshots, the old one breaking up as the new one resolves, with an ink riding the front between them. Give it a target to change one element while the page stays live, or none for the whole page: this site moves between its pages and turns its theme that way. Without the View Transitions API, under reduced motion or while the clock is directed, the change just happens.
- update
- Type() => void | Promise<void> (the change) Defaultnone
- direction
- Type'none' | 'right' | 'left' | 'down' | 'up' | 'iris' Default'none' (dissolve)
- origin
- Type{ x, y } (viewport px; the iris's centre) Defaultthe box's centre
- cell
- Typenumber (px) Default6
- band
- Typenumber (cells) Default10
- seed
- Typenumber (a seeded 4×4 matrix) Defaultnone (Bayer 8×8)
- ink
- Typestring (a CSS colour between the two) Defaultnone
- duration
- Typenumber (ms) Default600
- easing
- TypeEasingInput Default'ease-in-out'
- target
- TypeHTMLElement (the element that changes) Defaultthe whole page
Sticker peel
A corner of the card peels up on hover with a soft curl shadow: the sticker lift. Hover the card.
- children
- Typecontent Defaultnone
Expand tabs
An icon bar where only the active tab unfolds its label. The rest stay square glyphs. The label slides through the house 0fr grid trick.
- tabs
- Type{ value, label, color? }[] Defaultrequired
- modelValue
- Typestring (with onUpdateModelValue) Defaultrequired
- color
- TypePixelColor: active glyph fallback Default"blue"
Island
A morphing status pill: the compact row keeps its pulse while the detail unfolds beneath. Escape collapses; reduced motion snaps.
- modelValue
- Typeboolean (with onUpdateModelValue): expanded Defaultfalse
- label
- Typestring: compact row text Default"Status"
- color
- TypePixelColor: status dot Default"green"
- live
- Typeboolean: pulse the dot while collapsed Defaulttrue
- compact / children
- TypeJSX.Element (children: the detail panel) Defaultnone
Card stack
A swipe deck on the kit's own gesture math: 1:1 tracking, rubber-band past the edge, a flick or a far drag sends the card flying and the stack rises. Drag the top card.
- items
- TypeT[]: cycled forever Defaultrequired
- depth
- Typenumber: visible under-cards Default2
- children
- Type({ item, index, top }) => JSX.Element Defaultcard face fallback
- onAdvance
- Type(index) after a card flies out Defaultnone
Dock
A hover-magnifying dock: items swell on a gaussian falloff around the pointer and settle when it leaves. Reduced motion keeps the row still.
- items
- Type{ value, label, color? }[] Defaultrequired
- magnify
- Typenumber: peak scale over the pointer Default1.7
- range
- Typenumber (px): gaussian falloff radius Default80
- onSelect
- Type(value) Defaultnone
Preview rail
A Codex app-inspired navigation rail: compact ticks form a pyramid around the pointer and reveal a floating destination preview beside the rail. Keyboard focus previews too; reduced motion keeps the ticks still.
- items
- Type{ value, label, hint?, color? }[] Defaultrequired
- modelValue
- Typestring (with onUpdateModelValue): active destination Defaultundefined
- range
- Typenumber (px): pyramid falloff radius Default56
- side
- Type"left" | "right": edge the rail hugs Default"left"
- preview
- Type({ item }) => JSX.Element (custom preview content) Defaultlabel + hint
Scroll progress
Reading progress as a dithered bar. It composes DitherProgress and rides the viewport edge, or the top of any scrollable parent. Scroll the box.
- attach
- Type"viewport" | "parent" Default"viewport"
- edge
- Type"top" | "bottom" Default"top"
- color
- TypePixelColor Default"green"
Bouncy accordion
A single-open accordion with a weighted spring layout: panels overshoot and settle on a sampled damped-spring easing, icon rows lead each header, and content rises into view. Reduced motion reveals instantly.
- items
- Type{ value, label, hint?, icon?, color?, content? }[] Defaultrequired
- modelValue
- Typestring (with onUpdateModelValue): open item, "" closes all Default""
- color
- TypePixelColor: icon fallback tint Default"blue"
- slots
- TypeRecord<value, JSX.Element>: rich panel content (else item.content) Defaultnone
Expanding arrow
An accent tile that expands into a dotted-arrow trail on hover or focus. The trail is stamped from the same accent hue. Reduced motion reveals it instantly.
- color
- TypePixelColor: tile and trail accent Default"blue"
- disabled
- Typeboolean Defaultfalse
- children
- Typelabel content Default"Explore the kit"
Slide action
Drag the thumb to the end of the track to confirm (flick momentum counts), or release early and it springs back. Enter or Space confirms without the slide.
- label
- Typestring: track text and thumb aria-label Default"Slide to confirm"
- color
- TypePixelColor: thumb accent Default"green"
- disabled
- Typeboolean Defaultfalse
- onConfirm
- Type() when the thumb reaches the end, or Enter/Space Defaultnone
Hold action
Hold to complete: a liquid fill with a dotted crest rises (or slides) while you press; release early and it drains back. A held Enter or Space works the same way.
- duration
- Typenumber (ms): hold time to complete Default1200
- direction
- Type"vertical" | "horizontal": fill axis Default"vertical"
- color
- TypePixelColor: fill and crest accent Default"orange"
- disabled
- Typeboolean Defaultfalse
- onComplete
- Type() when the fill reaches full, once per hold Defaultnone
Wallet card
A wallet overview card: the account switcher and search morph open from their triggers (recents listed in the panel), the balance cascades in with a change pill and privacy toggle, the address copies with feedback, the bell carries an unread pulse, and Send / Deposit / Swap / Buy report through one event.
- accounts
- Type{ value, label, address, balance, change?, color? }[] Defaultrequired
- modelValue
- Typestring (with onUpdateModelValue): selected account Defaultfirst account
- balance / change
- Typenumber: override the active account's numbers Defaultaccount data
- currency
- Typestring: balance prefix Default"$"
- defaultHidden
- Typeboolean: start masked Defaultfalse
- searchPlaceholder
- Typestring Default"Search…"
- recent
- Typestring[]: recent queries in the search panel Defaultundefined
- notifications
- Typeboolean: unread pulse on the bell Defaultfalse
- color
- TypePixelColor: card accent Default"green"
- onAction
- Type("send" | "deposit" | "swap" | "buy") Defaultnone
- onSearch
- Type(query), live text on every keystroke Defaultnone
- onSubmit
- Type(query) on Enter or a recent row Defaultnone
- onNotify
- Type() when the bell is pressed Defaultnone
Notification stack
Compact notification cards that spring from a stacked summary into a readable list on hover, focus or tap. Tap pins the list open, and the view-all row appears with the expansion. Reduced motion snaps.
Variants
- items
- Type{ id, title, body?, time?, icon?, color? }[] Defaultrequired
- modelValue
- Typeboolean (with onUpdateModelValue): pinned open; hover/focus expand transiently Defaultfalse
- maxVisible
- Typenumber: cards shown in the stack and list Default3
- collapsedLabel
- Typestring: header + toggle aria-label Default"Notifications"
- expandedLabel
- Typestring: view-all button text Default"View all"
- emptyLabel
- Typestring: empty-state card Default"All caught up"
- variant
- Type"stack" | "fan" | "condensed": collapsed silhouette Default"stack"
- color
- TypePixelColor: icon fallback tint Default"blue"
- onViewall
- Type() when view-all is pressed Defaultnone
Step timing
Quantized time for a quantized renderer: steps() samples progress instead of interpolating it, the temporal twin of the Bayer threshold. One keyframe run, three clocks: smooth, six-step (both endpoints visible), three-step (the end value lands only on the last frame).
The kit's shared field runtime takes the same idea down at the driver layer: frameRate paints only on wall-time boundaries and holds the raster between them: stop-motion and fewer buffer uploads. Two Auroras, same clock source, different cadence.
- steps(n, position?)
- Type(p) => number, css-easing-1 step positions Default"jump-end"
- frameSteps(fps, durationMs)
- Type(p) => number, frame(fps) cadence polyfill Defaultnone
- frameIndex(elapsedMs, fps)
- Typenumber: wall-clock frame gate for drivers Defaultnone
- cssSteps(n, position?)
- Typestring: one config serialized for CSS Default"jump-end"
- DitherAurora frameRate
- Typenumber (fps) Default0 (smooth)
Sequences
Many animations, one clock. The timeline algebra flattens serial chains, parallel groups, staggered waves and loops into a single plan; the driver samples it and writes --seq-p + data-seq onto each child. Children style themselves, the engine only owns time. Ease with steps() and the whole wave quantizes.
Each cell reads only its own --seq-p: rise on the forward leg, sink on the yoyo leg, three cycles, settled at 1. Change the origin and the delay wave recomputes; quantize and steps(4) buckets the entire group into four positions. Reduced motion gets the settled state with zero frames.
- stagger
- Typenumber: seconds between neighbouring children Default0.06
- from
- Type"start" | "center" | "end" | "edges" | literal index Default"start"
- duration / easing
- Typenumber (s per cycle) / (p) => number from timing.ts Default0.5 / linear
- loop / yoyo / delay
- Typenumber / boolean / seconds before the timeline Default1 / false / 0
- paused / restartOnView / frameRate
- Typeboolean / boolean / fps cadence Defaultfalse / false / 0
- restartKey / onComplete
- Typestring | number (bump rebuilds and replays) / () => void Defaultnone
- planSequence(node | node[])
- TypeSequencePlan: flatten serial | parallel | stagger | track once Defaultnone
- sampleSequence(plan, t)
- TypeTrackSample[]: { id, index, progress, raw, cycle, state } Defaultnone
- staggerDelay(i, count, each, from)
- Typenumber: the delay wave, testable alone Defaultnone
Container queries
A card in a sidebar and the same card in a wide main column are not the same card, so stop asking the viewport. DitherContainer makes its own box the query target: it measures the content box (exactly what @container sees), resolves a bucket scale onto data-cq + --cq-w / --cq-i, and exposes the same state through its function child. Children restyle themselves in CSS while animations re-parameterize in JS.
The grid re-columns purely from [data-cq] (CSS reading the container's own state), while the Sequence's stagger, origin and replay derive from the same bucket through the child. Narrow it to xs and the wave tightens to 0.03s/cell; widen to xl and it fans from the center at 0.11s. quantize() rounds widths to the step so readouts and canvas painters hold like frames: the spatial half of the timing engine's step idea. This demo overrides scale so all five buckets fit the docs column; the default CONTAINER_SCALE targets wider shells. The blue bar runs the shipped dither-cq-traverse keyframe: translateX(±100cqw) makes its journey exactly one container width, so a resize re-scales the animation live, where translateX(50%) would measure the bar itself and vw would measure the viewport.
- scale
- TypeCqScale: Record<name, min | { min?, max? }>; min inclusive, max exclusive, order irrelevant DefaultCONTAINER_SCALE (xs 0, sm 240, md 360, lg 520, xl 720)
- step
- Typenumber: quantize --cq-w to this px (0 = continuous) Default0
- name
- Typestring: native container-name for children's @container rules Default"dither"
- as / class
- Typeelement tag / passthrough class Default"div" / none
- children
- Typefunction of { width, height, size, index, matches }: measured content box (what @container sees), active bucket, its ordinal, every matching bucket Defaultnone
- resolveCq(width, scale?)
- TypeCqState: the pure resolver (active = highest matching min) DefaultCONTAINER_SCALE
- quantize(value, step)
- Typenumber: nearest step, never negative; step ≤ 0 is identity Defaultnone
- data-cq / --cq-w / --cq-h / --cq-i
- Typeactive bucket attribute + content-box width/height (raw or quantized together) + ordinal, published on the host for CSS Defaultnone
- dither-cq-traverse / dither-cq-rise
- Typeshipped @keyframes: translateX(±100cqw) / translateY(±100cqh); motion measured against the container (small-viewport fallback when none) Defaultnone
Stage
Layers in container units. A DitherStage is a size query container with one clock (the kit's, so it seeks for video), and each DitherLayer runs keyframes whose lengths keep their units through interpolation: 10cqw to 30cqw is 20cqw halfway, mixed units become a calc(). Canvas, SVG and DOM layers move exactly relative to the stage at any size, and the same sample resolves to px through the child for anything that paints. Shrink the stage: every path shrinks with it.
The aurora is a canvas surface riding a layer: it drifts twelve percent of the stage, never twelve percent of the viewport. The two hills are SVGs on their own layers at two speeds: parallax in container units. The moon places its keys with at (seconds or a percentage) and eases one segment. The last layer keeps custom keys, cx and cy, which the child is handed resolved to px against the measured box: exactly the numbers a canvas painter needs. Nothing here is a CSS animation: the stage's clock samples every track, so a frame exported to video lands on the same moment.
- duration
- Typenumber (s): the stage clock loops over it; unset, time runs on Defaultnone
- speed
- Typenumber: clock multiplier Default1
- paused / frameRate
- Typeboolean / number (fps, 0 = smooth) Defaultfalse / 0
- restartKey
- Typeunknown: change to restart from 0 Defaultnone
- as / class
- Typeelement tag / passthrough class. Give the stage a height: it is a size query container Default"div" / none
- children
- Typefunction of { time, width, height }: the moment and the measured content box Defaultnone
- data-stage / --cq-w / --cq-h
- Typeplaying | directed | paused | still, and the box for CSS Defaultnone
- keyframes
- TypeKeyframe[]: { at? (s or '50%'), easing?, x, y (lengths: px, %, cqw, cqh, cqi, cqb, cqmin, cqmax, vw…, calc()), rotate, skewX, skewY (angles), scale, scaleX, scaleY, opacity, ...custom numbers or lengths } Default[]
- duration
- Typenumber (s): unset, the last key's at in seconds, else 1 Defaultnone
- delay / loop / yoyo
- Typenumber (s) / number | true / boolean Default0 / 1 / false
- easing
- Type'linear' | 'ease-out' | 'ease-in-out' | bezier points | seed | Easing: between keys; a key's own easing wins for the segment it starts Defaultlinear
- origin
- Typestring: transform-origin, container units welcome Default"50% 50%"
- as / class
- Typeelement tag / class (the layer is absolute, inset 0) Default"div" / none
- children
- Typefunction of every property resolved to px / degrees against the stage box, plus progress, cycle, time, width, height (the state is data-layer) Defaultnone
- style / data-layer
- Typetransform in the keyframes' own units, opacity, --layer-p and --layer-<name> per property; before | active | done Defaultnone
- sampleKeyframes(track, t), keyframeTransform(sample, box?), resolveSample(sample, box), parseLength / termsToCss / termsToPx
- Typethe engine alone, for your own painters and timelines Defaultnone
Print screens
Every surface thresholds its density through a 4x4 matrix, the Bayer one unless told otherwise. DitherScreen swaps it for a printer's screen for everything inside it: lines, a falling hatch, clustered dots or a cross-hatch, charts included. A surface's seed still jitters whichever screen it prints through, and screenMatrix hands the same thresholds to a painter of your own.
- screen
- Type'bayer' | 'line' | 'diagonal' | 'dot' | 'cross' Default'diagonal'
- children
- Typecontent (every surface inside prints through the screen) Defaultnone