# 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)
- [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) | — (HTML only) |

---

## Browse the demo

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

The demo lets you:
- Browse **72 illustrations** (Global and Dashboards) and **113 integration logos**
- Switch between **Illustrations** and **Integrations** 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

There is no React component for integrations — use the HTML approach directly.

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

---

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

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

---

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

---

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