dot-illustrations

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

📖 Browse the demo →

Contents

• Asset types
• Browse the demo
• Using illustrations
• Using integration logos
• Adding a new illustration or integration logo
  • Option A — Upload via demo UI (recommended)
  • Option B — Manual contribution
• 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

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 →

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

<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

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/). 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:

# 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

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:

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

   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:

   .dot-integration img.my-tool {
       content: url('./integrations/my-tool.svg');
   }

3. Add the ID to demo/script.js inside integrationsList, alphabetically ordered:

   const integrationsList = [
     "microsoft-teams",
     "my-tool",     // ← inserted alphabetically
     "mysql",
   ];

4. Open a pull request and post in #dot-components on Slack for review.

Troubleshooting

Latest dot-illustrations not picked up by dot-components

Add a resolutions entry to your package.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