# @digital-ai/dot-illustrations

> A central place for the design team to keep illustrations and for dev teams to find them.

Latest version **2.0.55** (published 2026-09-11) · SEE LICENSE IN <LICENSE.md> license · 0 weekly downloads

## Install

```sh
npm install @digital-ai/dot-illustrations
pnpm add @digital-ai/dot-illustrations
yarn add @digital-ai/dot-illustrations
bun add @digital-ai/dot-illustrations
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.0.55 |
| Published | 2026-09-11 |
| First published | 2024-03-12 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN <LICENSE.md> |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 3.4 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | gvolarevic-dai, agavaldas, msnively, jcaldas, geekzoo-dai, dai-npmjs-bot, grantcroker-dai |

## Links

- npm: https://www.npmjs.com/package/@digital-ai/dot-illustrations
- Repository: https://github.com/digital-ai/dot-illustrations
- Homepage: https://github.com/digital-ai/dot-illustrations/
- Issues: https://github.com/digital-ai/dot-illustrations/issues
- npm.io page: https://npm.io/package/@digital-ai/dot-illustrations

## Recent versions

- 2.0.55 (latest) — 2026-09-11
- 2.0.54 — 2026-09-10
- 2.0.53 — 2026-09-10
- 2.0.52 — 2026-08-27
- 2.0.51 — 2026-08-26
- 2.0.50 — 2026-08-18
- 2.0.49 — 2026-08-18
- 2.0.48 — 2026-08-18
- 2.0.47 — 2026-07-20
- 2.0.46 — 2026-07-10
- 2.0.45 — 2026-07-09
- 2.0.43 — 2026-06-04
- 2.0.42 — 2026-06-04
- 2.0.41 — 2026-06-03
- 2.0.40 — 2026-06-03
- … 70 more at https://npm.io/package/@digital-ai/dot-illustrations/versions

## README

# 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)
  - [Option A — Upload via demo UI (recommended)](#option-a--upload-via-demo-ui-recommended)
  - [Option B — Manual contribution](#option-b--manual-contribution)
- [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 **72 illustrations** (Global and Dashboards), **113 integration logos**, and **task icons** (Tasks section — inventory pending, see above)
- 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 — 113 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** directly from the browser

---

## 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';

<DotIllustration illustrationId="jenkins" ariaLabel="Jenkins" />
```

Same component as [illustrations](#using-illustrations) — integration logos
are just backed by a single-theme SVG in `integrations/` instead of a
light/dark pair in `illustrations/`.

### Standard HTML

```html
<link rel="stylesheet" href="./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" ariaLabel="Manual task" />
```

Same component as [illustrations](#using-illustrations) and
[integration logos](#using-integration-logos) — task icons are just backed
by a single-theme SVG in `tasks/` instead of a light/dark pair.

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

### Option A — Upload via demo UI (recommended)

The demo includes a built-in upload flow that handles everything automatically.

#### Prerequisites

**On the hosted demo** (`digital-ai.github.io/dot-illustrations/demo/`): nothing to run yourself — click **Connect GitHub** and follow the device-code prompt. This works because a maintainer has deployed the `demo/oauth-proxy/` Worker + registered a GitHub OAuth App (one-time setup, see [`demo/oauth-proxy/`](demo/oauth-proxy/)). GitHub's device-flow endpoints don't support CORS, so the browser can't call them directly — the Worker forwards those two calls server-to-server. It holds no secrets; Device Flow for public OAuth Apps only needs the Client ID.

If that isn't configured yet, **Connect GitHub** falls back to a manual Personal Access Token paste-in (scope: `public_repo`).

**Running locally instead:** run the local proxy once so the demo can authenticate as you without entering a token:

```bash
# From the repo root (requires gh CLI authenticated: gh auth login)
node demo/local-proxy.js
```

#### Steps

1. Open **https://digital-ai.github.io/dot-illustrations/demo/** (or your local server)
2. Click **Upload New** in the header
3. Choose what you are uploading:

**Illustration**
- Enter the **Illustration ID** (lowercase, hyphens only — e.g. `my-new-state`)
- Select the **Category**: Global or Dashboards
- Upload the **Light SVG** (☀️) and **Dark SVG** (🌙) — both are required
- Click **Connect GitHub** (device-code prompt on the hosted demo, local `gh auth` session with the local proxy running, or PAT paste-in fallback) then **Create Pull Request**

**Integration logo**
- Enter the **Integration ID** (lowercase, hyphens — e.g. `my-tool`)
- Upload the single **SVG** file (no dark variant needed)
- Click **Connect GitHub** (device-code prompt on the hosted demo, local `gh auth` session with the local proxy running, or PAT paste-in fallback) then **Create Pull Request**

**Task icon**
- Enter the **Task icon ID** (lowercase, hyphens — e.g. `task-priority-high`)
- Upload the single **SVG** file (no dark variant needed)
- Click **Connect GitHub** (device-code prompt on the hosted demo, local `gh auth` session with the local proxy running, or PAT paste-in fallback) then **Create Pull Request**

The PR is created automatically with:
- SVG file(s) committed to the correct folder
- CSS rule added to `index.css`
- ID added to `demo/script.js` in alphabetical order

> The local proxy uses your existing `gh auth` credentials — no token input required. The hosted demo's Connect GitHub button uses the device-flow proxy instead (see Prerequisites above); if it's not yet configured, it falls back to PAT paste-in.

---

### Option B — Manual contribution

Use this if the upload UI is not available.

#### Adding an illustration

1. Add your SVG files to the correct folders:
   ```
   illustrations/light/global/my-new-state.svg
   illustrations/dark/global/my-new-state.svg
   ```
   Use `dashboards/` instead of `global/` for dashboard-specific illustrations.

2. Add CSS rules to `index.css`:
   ```css
   .dot-illustration img.my-new-state.light {
       content: url('./illustrations/light/global/my-new-state.svg');
   }
   .dot-illustration img.my-new-state.dark {
       content: url('./illustrations/dark/global/my-new-state.svg');
   }
   ```

3. Add the ID to `demo/script.js` inside the correct list (`globalList` or `dashboardsList`), **alphabetically ordered**:
   ```js
   const globalList = [
     "add-new",
     "my-new-state",  // ← inserted alphabetically
     "no-chat",
   ];
   ```

#### Adding an integration logo

1. Add your SVG to `integrations/my-tool.svg`

2. Add a CSS rule to `index.css`:
   ```css
   .dot-integration img.my-tool {
       content: url('./integrations/my-tool.svg');
   }
   ```

3. Add the ID to `demo/script.js` inside `integrationsList`, **alphabetically ordered**:
   ```js
   const integrationsList = [
     "microsoft-teams",
     "my-tool",     // ← inserted alphabetically
     "mysql",
   ];
   ```

4. Open a pull request and post in [#dot-components](https://app.slack.com/client/T02GN6UQX/C01GVS9T7GV) on Slack for review.

#### Adding a task icon

1. Add your SVG to `tasks/my-task-icon.svg`

2. Add a CSS rule to `index.css` (under the `TASK ICONS` section):
   ```css
   .dot-task-icon img.my-task-icon {
       content: url('./tasks/my-task-icon.svg');
   }
   ```

3. Add the ID to `demo/script.js`'s `taskIconsList`, **alphabetically ordered**.

4. Open a pull request and post in [#dot-components](https://app.slack.com/client/T02GN6UQX/C01GVS9T7GV) on Slack for review.

---

## 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 CSS is imported: `<link rel="stylesheet" href="./index.css" />`. 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)

---
_Source: https://npm.io/package/@digital-ai/dot-illustrations · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._