# Installation

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

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. The dithercn agent skill, for building any dither on the engine, is at [/.well-known/agent-skills/dithercn/SKILL.md](/.well-known/agent-skills/dithercn/SKILL.md).

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 [#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.

```text
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 the dither I asked for on the engine, coloured from my theme. The example components are references: install one only if it is exactly what I asked for. Otherwise write your own field on DitherShader and borrow technique from the closest example's source.
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 [#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](https://ui.shadcn.com/docs/installation) first.

## Add the skill with the skills CLI [#add-the-skill-with-the-skills-cli]

The [skills CLI](https://skills.sh) installs the skill into Claude Code, Codex, Cursor, Gemini CLI and other agents that read skills. Run it in your project:

```bash
npx 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 [#or-add-the-engine-and-the-skill-with-shadcn]

  ### Run the add command [#run-the-add-command]

  ```bash
  npx 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](https://agentskills.io) 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 [#check-your-css]

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

  ```css
  @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](/docs/theming) lists every variable.

Then ask your agent for a dither. The [introduction](/docs#ask-your-agent-for-a-dither) has example requests and explains what the agent does with them.

## What's in the skill [#whats-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 [#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:

```bash
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 [#install-the-engine-or-one-example]

Without the skill, install the engine on its own:

```bash
npx 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:

```bash
npx shadcn@latest add https://dithercn.dev/r/dither-gradient.json
```

## Update the engine [#update-the-engine]

The engine is plain source in your project, so it doesn't update on its own. Newer docs can use features your copy lacks: if TypeScript says a prop such as `colorField` doesn't exist on `DitherShader`, delete `lib/dither` and add the engine again:

```bash
rm -rf lib/dither
npx shadcn@latest add https://dithercn.dev/r/dither-core.json https://dithercn.dev/r/dither-export.json
```

If the CLI asks whether to overwrite `lib/utils.ts`, answer no. Avoid `--overwrite`, which replaces that file too. If you edited any file in `lib/dither`, copy your changes out first.

## Use a namespace [#use-a-namespace]

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

```json title="components.json"
{
  "registries": {
    "@dithercn": "https://dithercn.dev/r/{name}.json"
  }
}
```

Then install with the `@dithercn` prefix:

```bash
npx shadcn@latest add @dithercn/dithercn-skill
```

See the shadcn docs on [namespaced registries](https://ui.shadcn.com/docs/registry/namespace) for more options, including authentication.

## Other ways in for agents [#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`](/llms.txt) lists every docs page with a one-line description and a Markdown link, and [`/llms-full.txt`](/llms-full.txt) is the whole documentation as one file.
* Add `.md` to any docs URL for its Markdown, for example [`/docs/installation.md`](/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`](/r/registry.json), and each item at `/r/<name>.json`. The [shadcn MCP server](https://ui.shadcn.com/docs/mcp) can browse and install from it once you have [added the `@dithercn` namespace](#use-a-namespace).
* [`/.well-known/api-catalog`](/.well-known/api-catalog) links every machine-readable surface (RFC 9727), [`/openapi.json`](/openapi.json) describes the read-only endpoints, and [`/api/status`](/api/status) returns `{"status":"ok"}`. The home page sends these as `Link` headers too.

## Next steps [#next-steps]

* [Ask your agent for a dither](/docs#ask-your-agent-for-a-dither) with the skill installed.
* Browse the [catalog](/docs/examples) for a component to install as it is.
* [Write your own dither](/docs/engine/write-your-own) by hand, step by step.