Introduction

dithercn is a dither engine with an agent skill. Ask your coding agent for a dither, say "a dithered topographic background behind the hero" or "a radial usage meter for the billing card", and it builds that component on the engine, in your shadcn theme, with motion, light and dark mode and reduced motion handled.

The components in these docs are examples of what the engine can make. Install one when it fits, read its source when you want to see how it was done, and ask your agent for something new when it doesn't.

What you get

• The engine. dither-core installs into lib/dither as plain source. It turns a tone you compute into dither dots: a WebGL shader for anything that moves or varies per pixel, SVG patterns and CSS masks for static fills, image dithering, and export to PNG, SVG and CSS.
• The agent skill. A SKILL.md and references that teach Claude Code, Codex, Cursor and other agents the engine: how to pick a technique, write a field, place it on a page, colour it from your theme and check it in a browser. Installation adds it to your project.
• The examples. More than forty backgrounds, charts, interface pieces, text effects and image treatments, each installable with npx shadcn add. Browse them in the catalog.

What a dither is

A dither draws a smooth tone using only a few colours. It places dots of ink at a density that matches the tone, so your eye blends them into a gradient. Dithering began as a workaround for limited screens and printers. It now reads as a deliberate texture, a little like risograph print, and it suits both a hero that should feel crafted and a dashboard that should feel calm.

Ask your agent for a dither

Once the skill is installed, describe what you want and where it goes. Name the page, the mood and anything that must stay readable:

• "Add a dithered topographic contour background behind the hero on the home page. Slow, quiet, readable headline."
• "On the billing page, add a dithered radial meter for storage used, 72%, with the number in the middle."
• "Make the pricing section's top edge dissolve into the page with a dithered fade in our accent colour."
• "Dither the team photos in the about page in our primary colour, and make them sharpen on hover."
• "Replace the empty state on the inbox with a small dithered illustration of a paper plane."

You don't need to know which component or API fits. The skill sends the agent through four steps:

1. Set up the engine. It checks for lib/dither and installs dither-core if it's missing.
2. Pick a technique. A WebGL field for anything that moves or varies per pixel, SVG patterns for chart and meter fills, CSS masks for blocks and bars, image dithering for photos, and export for files. If an example in the catalog is close, it installs that and edits it.
3. Build the component. It writes a typed component with props you can tweak, places it behind or inside your content, and colours it from your theme.
4. Check it in a browser. It looks at the result in light and dark mode, at desktop and phone widths and with reduced motion, and fixes what doesn't read.

How the docs are organised

• Get started: this page, Installation and Theming.
• Examples: the catalog of every component, then one page per component, grouped into Backgrounds, Charts, Interface, Text and Images.
• Engine: how dither-core works, for when you want to build a dither yourself. Start with the dither engine and Write your own dither.

Principles

• Your theme, not ours. Dithers read your --primary and --background tokens through the --dither-* variables, so they change when your theme changes.
• Quiet by default. Motion is slow, and every animated dither holds still when the visitor prefers reduced motion.
• Cheap on dashboards. Static fills are SVG patterns and CSS masks, and shaders draw one pixel per cell and stop when they scroll out of view.
• Real text stays text. Dithered headings and labels are still HTML, so they can be selected, read aloud and indexed.
• Source you own. Everything installs as files in your project. You and your agent can read and change all of it.

Credits

DitherKit by Boring Software set the bar for this project. The fill variants, bloom, named colours, scrubbing chart tooltip, legend spotlight and lock, docs knobs, generative avatars and the button that thickens its dither on hover all started as ideas we saw there. The code and the look are our own. DitherKit credits EvilCharts for the dithered chart style it grew from, so thanks to both.