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

<AgentPrompt name="quick-start" />

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:

<CommandBox tool="skills" className="mt-6" />

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]

<Steps>
  ### 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.
</Steps>

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
```

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