# dot-illustrations

Central asset library for Digital.ai UX — illustrations and integration logos for use in products and documentation.

📖 **[Browse the demo →](https://digital-ai.github.io/dot-illustrations/demo/)**

---

## Contents

- [Asset types](#asset-types)
- [Browse the demo](#browse-the-demo)
- [Using illustrations](#using-illustrations)
- [Using integration logos](#using-integration-logos)
- [Using task icons](#using-task-icons)
- [Adding a new illustration or integration logo](#adding-a-new-illustration-or-integration-logo)
- [Troubleshooting](#troubleshooting)

---

## Asset types

| Type | Folder | Themes | React component |
|---|---|---|---|
| **Illustrations** | `illustrations/light/` + `illustrations/dark/` | Light + Dark | `DotIllustration` |
| **Integration logos** | `integrations/` | Single (no dark variant) | `DotIllustration` |
| **Task icons** | `tasks/` | Single (no dark variant) | `DotIllustration` |

> **Integration logos and task icons are `DotIllustration`, not a separate
> icon component** — same component as Illustrations, just backed by a
> single-theme SVG instead of a light/dark pair. **Task icons** are new
> (S-135988) — fixed-color pipeline/workflow badge icons sourced from the dot
> atomic library (Figma node `27123-30795`). 13 of the node's 15 icons are in
> scope (2 are excluded as AI-styled). SVGs are in place. See
> [`tasks/README.md`](tasks/README.md) for status.

---

## Browse the demo

**https://digital-ai.github.io/dot-illustrations/demo/**

The demo lets you:
- Browse **73 illustrations** (Global and Dashboards), **114 integration logos**, and **13 task icons** (Tasks section)
- Switch between **Illustrations**, **Integrations**, and **Tasks** using the section switcher next to the search bar
- **Search** with fuzzy autocomplete across both sections
- Filter illustrations by **A–Z** (integrations only — 114 logos benefit from alphabet navigation)
- **Click any card** to open a detail modal with the copy-ready code snippet
- **Star items** to save them in your Favourites (persisted in your browser)
- **Upload a new illustration or integration logo** from the browser (see [Upload New](docs/adding-assets.md#upload-new-in-the-demo))

---

## Using illustrations

### React — `DotIllustration` via `dot-components`

```tsx
import { DotIllustration } from '@digital-ai/dot-components';

// Light (default)
<DotIllustration illustrationId="empty" />

// Dark
<DotIllustration illustrationId="done" theme="dark" />

// With tooltip
<DotIllustration illustrationId="features" tooltip="See all features" />
```

[Full `DotIllustration` documentation →](https://digital-ai.github.io/dot-components/?path=/story/components-illustration--default)

### Standard HTML

```html
<link rel="stylesheet" href="./index.css" />

<!-- Light theme -->
<span class="dot-illustration">
  <img class="done light" />
</span>

<!-- Dark theme -->
<span class="dot-illustration">
  <img class="done dark" />
</span>
```

Always set an explicit `width` and `height` — the library has no built-in sizing defaults.

---

## Using integration logos

### React — `DotIllustration` via `dot-components`

```tsx
import { DotIllustration } from '@digital-ai/dot-components';
import '@digital-ai/dot-illustrations/integrations/index.css';

<DotIllustration illustrationId="jenkins" className="dot-integration" ariaLabel="Jenkins" />
```

> **Workaround:** `DotIllustration` doesn't support integration logos on its
> own. It loads only the root `index.css` and wraps the image in
> `.dot-illustration`, but integration rules are `.dot-integration img.<id>`
> in `integrations/index.css`. Import that file once in your app and pass
> `className="dot-integration"`, which adds the class to the wrapper. Without
> both, the image renders empty.

### Standard HTML

```html
<link rel="stylesheet" href="./integrations/index.css" />

<span class="dot-integration">
  <img class="jenkins" />
</span>
```

> Integration logos are **single-theme only** — they have no dark variant.

---

## Using task icons

### React — `DotIllustration` via `dot-components`

```tsx
import { DotIllustration } from '@digital-ai/dot-components';

<DotIllustration illustrationId="task-manual" className="dot-task-icon" ariaLabel="Manual task" />
```

> **Workaround:** `DotIllustration` doesn't support task icons on its own. It
> wraps the image in `.dot-illustration`, but task rules are
> `.dot-task-icon img.<id>`. They live in the root `index.css`, which
> `dot-components` already loads, so passing `className="dot-task-icon"` is
> enough. Without it, the image renders empty.

### Standard HTML

```html
<link rel="stylesheet" href="./index.css" />

<span class="dot-task-icon">
  <img class="task-manual" />
</span>
```

> Task icons are **single-theme only** — fixed-color badges, no dark variant.

> **Status:** the Tasks section ships with the browse/copy/upload UI wired up,
> the 13 in-scope icon IDs, and their SVGs are all in place — see
> [`tasks/README.md`](tasks/README.md). Still open: publishing these as real
> `iconId`s in `@digital-ai/dot-icons`.

---

## Adding a new illustration or integration logo

**Step-by-step guide for designers: [docs/adding-assets.md](docs/adding-assets.md)**. It covers illustrations, integration logos and task icons: the Figma export, the files, the `illustrations.json` line, the check's messages and what happens after the merge.

In short, every asset is listed once in [`illustrations.json`](illustrations.json), and `npm run build` writes `index.css`, `integrations/index.css`, the demo lists and `demo/descriptions.json` from it. Don't edit those by hand.

1. On a new branch, add the SVG files:

   | Kind | Files | Size |
   |---|---|---|
   | Illustration | `illustrations/light/global/my-new-state.svg` and `illustrations/dark/global/my-new-state.svg` (use `dashboards/` for a dashboard illustration) | 248 × 248 (dashboards 353 × 212) |
   | Integration logo | `integrations/my-tool.svg` | 40 × 40 |
   | Task icon | `tasks/my-task-icon.svg` | 40 × 40 |

2. Add one line to `illustrations.json`, at the end of its group (global illustrations, dashboard illustrations, integration logos, then task icons):
   ```json
   {"id":"my-new-state","kind":"illustration","category":"global","label":"My new state","description":"This is the my-new-state illustration."},
   {"id":"my-tool","kind":"integration","category":null,"label":"My tool","description":null},
   {"id":"my-task-icon","kind":"task","category":null,"label":"My task icon task","description":null},
   ```
   Ids are lowercase with hyphens. `label` is the aria label the demo's copied code uses. `category` and `description` are only for illustrations.

3. Run the build (Node 20 or later, no install needed), the tests and the check:
   ```bash
   npm run build
   npm test
   npm run check
   ```

4. Commit the SVGs, `illustrations.json` and the files the build changed. Open a pull request and post in [#dot-components](https://app.slack.com/client/T02GN6UQX/C01GVS9T7GV) on Slack for review.

**Upload New in the demo** does steps 1 and 2 in one commit, and checks each file and the id before it sends anything. The reviewer then runs `npm run build` on its branch and pushes before merging. It can't open pull requests from the hosted demo yet: the `digital-ai` organization's OAuth App access restrictions block its app. It works from a local copy of the demo with `node demo/local-proxy.js`. The [guide](docs/adding-assets.md#upload-new-in-the-demo) has the steps.

---

## Troubleshooting

**Latest `dot-illustrations` not picked up by `dot-components`**

Add a `resolutions` entry to your `package.json`:

```json
"resolutions": {
  "@digital-ai/dot-illustrations": "latest"
}
```

**Integration image not showing**

Make sure the integrations CSS is imported: `<link rel="stylesheet" href="./integrations/index.css" />`. In React, also pass `className="dot-integration"` (see [Using integration logos](#using-integration-logos)). The library uses `content: url()` on `<img>` elements — the `<img>` tag must have **no `src` attribute** and the class must match the integration ID exactly.

---

More information: [dot design system — Illustrations](https://zeroheight.com/4a9ac476a/p/86a804-illustrations)
