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
• Using task icons
• Adding a new illustration or integration logo
• Troubleshooting

Asset types

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

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

React — DotIllustration via dot-components

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

<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

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

<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. Still open: publishing these as real iconIds in @digital-ai/dot-icons.

Adding a new illustration or integration logo

Step-by-step guide for designers: 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, 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):

   {"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:

   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 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 has the steps.

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 integrations CSS is imported: <link rel="stylesheet" href="./integrations/index.css" />. In React, also pass className="dot-integration" (see 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