fluidither

A component library with a printed look: ink on paper, soft dithered shading where most interfaces use a flat tint, and every movement on a spring.

The web target is plain HTML, CSS and JavaScript, with no framework and no runtime dependencies. The GPUI target is a Rust crate. Both come from the same tokens, and tests hold their dither output to the same cells.

Every example on this page is the real component, running under the same strict policy the library promises to work under.

Install for the web

There is no build step. This copies the whole library into your project:

npx fluidither

It uses public/fluidither if the project has a public folder, and fluidither otherwise. Add --dir to choose another place.

Every page needs tokens.css, then the file for each component it uses. Scripts are ES modules, so serve the folder from a web server rather than opening the file.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Hello</title>
    <link rel="stylesheet" href="fluidither/tokens.css" />
    <link rel="stylesheet" href="fluidither/components/button.css" />
    <link rel="stylesheet" href="fluidither/components/tabs.css" />
    <link rel="stylesheet" href="site.css" />
    <script type="module" src="fluidither/components/tabs.js"></script>
  </head>
  <body>
    <fd-tabs value="week">
      <fd-tab-list aria-label="Date range">
        <fd-tab value="day">Day</fd-tab>
        <fd-tab value="week">Week</fd-tab>
      </fd-tab-list>
    </fd-tabs>

    <button class="fd-button" type="button">Save</button>
  </body>
</html>

tokens.css only defines values, so style the page yourself in site.css:

body {
  background: var(--fd-paper);
  color: var(--fd-ink);
  font-family: var(--fd-font-sans);
}

python3 -m http.server 8000

With a bundler, install the package and import the pieces by name:

npm install fluidither

import 'fluidither/tokens.css';
import 'fluidither/components/tabs.css';
import 'fluidither/components/tabs.js';

Take only what you need

Pages load only the files they link, so copying everything costs nothing at runtime. To keep your project tidy as well, name the components instead:

npx fluidither add tabs button gradient

That copies those components, tokens.css and the files they import, then prints the tags to paste. Each component below shows its name. To see them all:

npx fluidither list

Run either command again to add more or to update what you have. --dir works on both.

Install for GPUI

Add the crate, with gpui at the same version:

[dependencies]
fluidither = "0.2"
gpui = { version = "=0.2.2", features = ["runtime_shaders"] }

Call fluidither::init(cx) once at startup. It sets the theme and makes Tab move focus.

use fluidither::{Button, Look, Theme};
use gpui::{div, prelude::*, px, App, Application, Context, Render, Window, WindowOptions};

struct Home;

impl Render for Home {
    fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        let colors = Theme::get(cx).colors();
        div()
            .size_full()
            .p(px(24.))
            .bg(colors.paper)
            .text_color(colors.ink)
            .child(Button::new("save", "Save").look(Look::Soft).on_click(|_, _, _| {}))
    }
}

fn main() {
    Application::new().run(|cx: &mut App| {
        fluidither::init(cx);
        cx.open_window(WindowOptions::default(), |_, cx| cx.new(|_| Home)).unwrap();
        cx.activate(true);
    });
}

Building needs no Metal toolchain, because shaders compile at startup. The first build compiles GPUI itself, which took about 10 minutes on an M1 Pro.

Most components are elements. Add them directly as children. They keep their own state, keyed by id, unless you pass the value in. The text field, combobox, command menu and composer are views, so create them once and keep the entity.

Agent skill

The skill teaches a coding agent to use and extend the library: the rules, a reference for each target, recipes for common screens, and how to add to both targets.

npx fluidither skill

That puts it in .agents/skills/fluidither. Add --dir for another place, such as ~/.claude/skills/fluidither for Claude Code.

Design

• Ink and paper. Warm neutrals, with color kept for meaning. Dark mode is light ink on dark paper, not an inverted page.
• Dither instead of tint. Hover states, dialog screens, chart shading and the empty part of a slider are real dithers, drawn cell by cell. Never put a dither behind body text.
• Springs instead of durations. Motion keeps its speed when the target changes, and reduced motion is respected.
• Pixel marks. Ticks, dashes and arrows are small cell drawings from the tokens, so they match on both targets.
• Two densities. regular and compact, set on any element.

Tokens

Use a token rather than a hard coded color or size. In a project that copied the source, override the custom properties in your own CSS, and leave the copied files alone.

:root {
  --fd-radius-control: 2px;
}

On GPUI, read them from Theme::get(cx).colors() and Density::tokens(). The main colors are paper, ink, ink_soft, line, edge, focus, soft, wash and surfaces[0] to surfaces[3], with the same six named colors.

Themes and density

Themes follow the system. Set data-theme="light" or "dark" on <html> to force one. data-density="compact" works on any element and applies to what is inside it.

On GPUI, set cx.global_mut::<Theme>().mode to Mode::Dark or Mode::Light, then call window.refresh(). Density is Density::Regular or Density::Compact.

Springs

There are three: quick for hover, glide for movement, and settle for arrivals. A spring keeps its speed when the target changes, stops by itself and honors reduced motion.

Things leave faster than they arrive. Each spring has an exit a step quicker, quickOut, glideOut and settleOut, or --fd-spring-quick-out and its siblings in CSS. Pass one to glide.to(targets, springs.quickOut) for a single move.

import { Glide, springs } from './fluidither/core/spring.js';

const glide = new Glide({ x: 0 }, springs.glide, ({ x }) => element.style.setProperty('--x', `${x}px`));
glide.to({ x: 120 });

On GPUI, hold a Spring::new(fluidither::generated::GLIDE, 0.0), set target, call step(dt) in render, and call window.request_animation_frame() until it returns true.

Gliding hover

One highlight moves between items, in place of each item blinking on and off. Your eye stays on the task, because there is only one thing to follow. It is a dither, so it reads as ink and never as a tint.

Reveal

Children rise into place one after another when they scroll into view, for a page read once. Add subtle for a smaller move. Content stays visible until the script runs, and reduced motion shows it at once. Call .run() to play it again.

Dithers

A tone from 0 to 1 is worked out for every cell, then compared with a threshold from a matrix. A cell above its threshold gets ink, so the output is a flat grid of ink and paper that stays crisp at any size.

Matrices are bayer2, bayer4, bayer8, halftone and blue-noise. Bayer looks crisp and patterned, blue noise looks organic, and halftone looks like print. Cells of 2 to 3px read as texture, and larger cells read as pixel art.

A canvas element's ink is its CSS color, and the paper is its background-color. Give gradients, fields and images a size in CSS. To dither a shape of your own, fill a tone array and threshold it:

import { ditherTones, thresholdMap } from './fluidither/core/dither.js';

const map = await thresholdMap('bayer4');
const tones = new Float64Array(width * height).map((_, index) => (index % width) / width);
const cells = new Uint8Array(width * height);
ditherTones(tones, width, height, map, Uint8Array.of(0, 1), cells);

To add a dithered hover to something new:

.thing:hover {
  --_dots: color-mix(in srgb, currentColor var(--fd-dither-hover-ink), transparent);
  background-image: repeating-conic-gradient(var(--_dots) 0 25%, transparent 0 50%);
  background-size: calc(var(--fd-dither-hover-cell) * 2) calc(var(--fd-dither-hover-cell) * 2);
}

Strict CSP

The web target has no inline styles and no data: images, so it runs under this policy. This page runs under it too.

default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self'

Keep your own code inside it: no style attributes and no <style> tags. Setting styles from JavaScript through the CSSOM is fine. Dither CSS masks built from data URLs are blocked, so use canvas or a repeating-conic-gradient.

Actions

Forms

Overlays

Dates

Structure

Feedback

Chat

Charts

Dither

import { savePng } from './fluidither/core/export.js';

savePng(element, 'name.png');

Text

Media

Recipes

A settings page

Use .fd-card sections holding .fd-field rows, with .fd-switch for on and off and <fd-select> for choices. Put a solid button last, with a soft one for cancel. Use data-density="compact" on the page if there's a lot of it.

A dashboard

A row of cards, each with a .fd-stat and an <fd-sparkline>, above one large <fd-chart> and a .fd-table. Use color for series, and tones for status with .fd-badge.

A hero band

<fd-dither-gradient class="band" angle="90" from="0" to="0.75" speed="0.4"></fd-dither-gradient>

.band {
  height: 120px;
  border-radius: 8px;
}

Use <fd-field kind="aurora"> for something livelier.

A command palette

Add <fd-command> once, and call .show() from your own shortcut. On GPUI, create a CommandMenu view, add it as a child, and call show.

Support

Vertical tabs, sortable tables, submenus and PDF previews are missing on both targets. GPUI also has no multi line text and no link style button. The full list of limits is on GitHub.

Performance

The last figure counts shared code more than once. There are no runtime dependencies. The frame costs for both targets are on GitHub.