Installation

Add the dithercn engine and agent skill to a shadcn project, or install a single example.

dithercn installs with the shadcn CLI, like any other registry. One command adds the engine and the agent skill; after that you ask your agent for dithers, or install examples one by one.

Quick start with your agent

Paste this prompt into Claude Code, Codex, Cursor or any other coding agent. It installs the engine and the skill, reads the docs and builds the dither you ask for. It's the same prompt the home page copies.

Add dithercn to this project and build me a dither with it.

1. Install the dithercn engine and agent skill with the shadcn CLI:
   npx shadcn@latest add https://dithercn.dev/r/dithercn-skill.json
   This writes lib/dither, the skill in .agents/skills/dithercn and .claude/skills/dithercn, and the --dither-* CSS variables. The project needs shadcn/ui, Tailwind CSS v4 and React 19.
2. Read .agents/skills/dithercn/SKILL.md and follow it for everything below. If it isn't on disk, read https://dithercn.dev/.well-known/agent-skills/dithercn/SKILL.md. The docs are at https://dithercn.dev/docs, and https://dithercn.dev/llms.txt lists every page as Markdown.
3. If I haven't said which dither I want and where it goes, ask me in one question, and suggest two or three that would suit this project.
4. Build it on the engine, coloured from my theme. Start from an example component if one is close.
5. Check it in a browser in light and dark mode, at desktop and phone widths and with reduced motion, and fix what doesn't read. Then tell me what you made and where.

The rest of this page does the same steps by hand.

Before you start

You need a project that already uses shadcn/ui, with a components.json file, Tailwind CSS v4 and React 19. If you don't have one yet, follow the shadcn installation guide first.

Add the skill with the skills CLI

The skills CLI installs the skill into Claude Code, Codex, Cursor, Gemini CLI and other agents that read skills. Run it in your project:

$ pnpm dlx skills add https://dithercn.dev

It asks which agents to install for, then writes the skill and its references into each agent's skills folder, such as .claude/skills/dithercn/ and .agents/skills/dithercn/. Add -g to install it for every project on your machine. The skill adds the engine to your project the first time your agent builds a dither.

Or add the engine and the skill with shadcn

Run the add command


$ pnpm dlx shadcn@latest add https://dithercn.dev/r/dithercn-skill.json

This writes:

lib/dither/, the engine (dither-core) and its export functions (dither-export).
.agents/skills/dithercn/ and .claude/skills/dithercn/, the agent skill. Claude Code reads .claude/skills; Codex, Cursor and other agents that follow the Agent Skills layout read .agents/skills.
The --dither-* CSS variables, in the CSS file named in your components.json.

Commit the skill folders with the rest of your code, so everyone on the project, and every agent, gets the same skill.

Check your CSS

The CLI adds the variables for light and dark mode, and colour utilities to the @theme inline block:

@theme inline {
  --color-dither-ink: var(--dither-ink);
  --color-dither-paper: var(--dither-paper);
  /* and one per named colour: --color-dither-blue, --color-dither-green, … */
}
 
@layer base {
  :root {
    --dither-ink: var(--primary);
    --dither-paper: var(--background);
    --dither-cell: 3px;
  }
  .dark {
    --dither-ink: var(--primary);
    --dither-paper: var(--background);
    --dither-cell: 3px;
  }
}

Because the variables point at your theme tokens, there is nothing extra to set for dark mode. Theming lists every variable.

Then ask your agent for a dither. The introduction has example requests and explains what the agent does with them.

What's in the skill

File	What it covers
`SKILL.md`	The four steps the agent follows, and the rules for every dither
`references/engine-api.md`	Every engine export: `DitherShader`, `FillPattern`, `fillStyle`, colours, motion hooks, `ditherImage` and export
`references/fields.md`	How to write a GLSL field, with building blocks for gradients, noise, contour lines, rings, arcs and shading
`references/recipes.md`	Complete components to adapt: a shader background, a hero that clears its headline, an SVG chart fill, a progress bar, a dithered photo, a CSS-only band
`references/landing-pages.md`	Designing the page around the dither: start from the product, one memorable hero, true copy, the tells to avoid
`references/placement.md`	Putting a dither on a landing page or dashboard: layering, sizing, server and client components
`references/theme.md`	Tokens, named colours, palettes, light and dark mode
`references/quality.md`	The checks: looks, contrast, reduced motion, accessibility, performance
`references/examples.md`	Every example component, with its install command and docs link

The skill matches the engine it installs with and points your agent at the files in your project, so it never has to guess at an API.

Install the skill for every project

shadcn add writes the skill into the current project only. To make it available in every project on your machine, run the skills CLI with -g. Without the CLI, download the files into your user skills folder:

SKILL=https://dithercn.dev/.well-known/agent-skills/dithercn
for dir in ~/.claude/skills/dithercn ~/.agents/skills/dithercn; do
  mkdir -p "$dir/references"
  curl -fsSL "$SKILL/SKILL.md" -o "$dir/SKILL.md"
  for ref in engine-api examples fields landing-pages placement quality recipes theme; do
    curl -fsSL "$SKILL/references/$ref.md" -o "$dir/references/$ref.md"
  done
done

The skill tells the agent to install the engine into a project the first time it needs it.

Install the engine or one example

Without the skill, install the engine on its own:


$ pnpm dlx shadcn@latest add https://dithercn.dev/r/dither-core.json

Or install any example. Each one brings the engine with it on its first install:


$ pnpm dlx shadcn@latest add https://dithercn.dev/r/dither-gradient.json

Use a namespace

To install by name instead of by URL, add dithercn to the registries field of your components.json:

components.json

{
  "registries": {
    "@dithercn": "https://dithercn.dev/r/{name}.json"
  }
}

Then install with the @dithercn prefix:


$ pnpm dlx shadcn@latest add @dithercn/dithercn-skill

See the shadcn docs on namespaced registries for more options, including authentication.

Other ways in for agents

The skill is the main way in. The site also publishes plain-text surfaces for agents that browse:

/llms.txt lists every docs page with a one-line description and a Markdown link, and /llms-full.txt is the whole documentation as one file.
Add .md to any docs URL for its Markdown, for example /docs/installation.md, or send an Accept: text/markdown header. Every page also has a Copy page menu.
The registry index is at /r/registry.json, and each item at /r/<name>.json. The shadcn MCP server can browse and install from it once you have added the @dithercn namespace.
/.well-known/api-catalog links every machine-readable surface (RFC 9727), /openapi.json describes the read-only endpoints, and /api/status returns {"status":"ok"}. The home page sends these as Link headers too.

Next steps

Ask your agent for a dither with the skill installed.
Browse the catalog for a component to install as it is.
Write your own dither by hand, step by step.

Introduction Theming

On This Page

Quick start with your agent Before you start Add the skill with the skills CLI Or add the engine and the skill with shadcn Run the add command Check your CSS What's in the skill Install the skill for every project Install the engine or one example Use a namespace Other ways in for agents Next steps

View as Markdown