dot-icons

Icon font repository for Digital.ai UX — used standalone or with dot-components.

📖 Browse the demo →

Contents

• Using icons
• Browse the demo
• Adding a new icon
  • How the font is built
  • Adding or changing an icon
  • Upload New in the demo
  • Export rules
• Checks on every pull request
• Configuring Jest
• Troubleshooting

Using icons

React — DotIcon via dot-components

import { DotIcon } from '@digital-ai/dot-components';

<DotIcon iconId="home" />
<DotIcon iconId="settings" fontSize="large" tooltip="Settings" />
<DotIcon iconId="ai" ai={true} />

Full DotIcon documentation →

Standard HTML

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

<span class="dot-icon">
  <i class="icon-home"></i>
</span>

Never add the icon- prefix to the iconId prop — DotIcon adds it automatically.

Browse the demo

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

The demo lets you:

• Browse every icon, organised into 12 categories (Navigation, Actions, Status, Layout, DevOps, Files & Docs, Communication, Security, People, AI, Logos, Business & Misc) plus your Favourites
• Search with fuzzy autocomplete, by id or by a legacy name (expander finds key)
• Click any card to open a detail modal with Icon ID, Dot Code (<DotIcon iconId="..." />), and HTML Code — all copyable
• Star icons to save them in your Favourites tab (persisted in your browser)
• Upload a new icon from the browser: Upload New checks the id and the SVG, then opens a pull request with the SVG and its icons.json line. On the hosted demo that works once the organization has approved the demo's GitHub app; until then, run the demo locally (see Upload New in the demo)

Adding a new icon

How the font is built

The repo is the source of the icon font. IcoMoon is no longer used: don't import or export IcoMoon projects, and don't edit selection.json by hand.

• fonts/svg/<id>.svg: one SVG per icon.
• icons.json: one line per icon, with its id, its code (the font code point), its demo category, and its aliases (legacy class names for the same glyph, such as expander for key).

npm run build generates everything else from those two: fonts/dot.woff2, dot.woff, dot.ttf and dot.svg, index.css, the demo's icon list (demo/icons.js), and selection.json. The same input always gives the same bytes. Don't edit a generated file by hand: the check on every pull request fails it.

selection.json is an IcoMoon project with every glyph, written for one more release as a way back to IcoMoon. After that the build stops writing it.

Adding or changing an icon

Step-by-step guide for designers: docs/adding-assets.md. It covers new icons, redraws, aliases, the naming rules, the check's messages and what happens after the merge.

In short:

1. Export the icon from Figma as an SVG that follows the export rules.
2. On a new branch, run npm ci once, then add the icon with its file, its id and an existing category:

   npm run add-icon -- ~/Downloads/my-new-icon.svg my-new-icon actions
   

   The id is lowercase kebab-case, like my-new-icon. add-icon checks the SVG, copies it to fonts/svg/<id>.svg, adds a line to icons.json with the next free code, and runs npm run build. It refuses to run on main, commits nothing, and changes no file when something is wrong.
3. Check the icon in the demo.
4. Commit the SVG, icons.json and every generated file, and open a pull request. When Check icons passes, post it in #dot-components on Slack.

To add an icon by hand instead, save the SVG as fonts/svg/<id>.svg, add one line at the end of icons.json with the next free code and a comma on the line before it, and run npm run build:

{"id":"my-new-icon","code":"ea3b","category":"actions","aliases":[]}

A redrawn icon needs the glyph-change label on its pull request. Ids are never renamed or removed; add a second name as an alias instead.

Upload New in the demo

Without a clone, add an icon from the demo: Connect GitHub, then Upload New, with the id, a category and the SVG file.

• The form checks as you go: the id as you type it (lowercase kebab-case, not taken by an icon or a legacy name), and the file as you pick it (an .svg that follows the export rules). It lists every problem, and Create Pull Request stays disabled until there are none.
• It opens a pull request with one commit: the SVG as fonts/svg/<id>.svg and one line in icons.json at the next free code. It doesn't build the font.
• Before the pull request merges, someone runs npm run build on its branch and pushes the result. Check icons stays red until then; the pull request says how.

The digital-ai organization restricts OAuth App access, so the hosted demo can open a pull request only once an org owner has approved its app. Until then, or if GitHub answers that the organization "has enabled OAuth App access restrictions", use npm run add-icon, or run the demo from your clone with your own gh sign-in (gh auth login). In two terminals, from the repo root:

node demo/local-proxy.js

python3 -m http.server 5174

Then open http://localhost:5174/demo/. It connects through the proxy on its own.

Export rules

A font glyph has one colour and no strokes, so add-icon, Upload New, npm run build and Check icons stop an SVG with:

• a stroke, an embedded image, a gradient, text, transparency, or a clip or mask other than the clip Figma adds for the frame
• more than one fill colour, or no filled shape
• a viewBox that isn't square, for a new icon: add-icon, Upload New and Check icons stop it, and npm run build doesn't, so the four 975-wide icons from IcoMoon keep their width
• more than 200 KiB, or a link to an outside file

fill-rule="evenodd", which Figma often exports, gives a warning only. In Figma: a square frame such as 24 × 24, Outline stroke and Outline text, then Flatten, and one fill for every shape. Each message and its fix: docs/adding-assets.md.

Checks on every pull request

The Check icons workflow rebuilds every pull request and compares it with its base branch. It fails when:

• a generated file doesn't match a fresh npm run build, for example after a hand edit to index.css or font files copied from an IcoMoon export
• a class name in index.css is removed, or points at a different code, for example icon-forward-outline was moved from \ea3a to \ea3b
• a glyph in fonts/dot.ttf is removed
• one of the font's vertical metrics changes, which would move every icon
• an existing glyph changes shape: its outline moves by more than 1 font unit, its width or number of contours changes, or a contour winds the other way
• icons.json breaks a rule: a duplicate id, alias or code, an entry without an SVG or an SVG without an entry, or a new icon whose code isn't above every earlier code, whose id isn't lowercase kebab-case, or whose category doesn't exist
• an SVG the pull request adds or changes breaks an export rule. Warnings show in the run's summary and don't fail it

New class names and new glyphs pass. If an existing icon is redrawn on purpose, add the glyph-change label to the pull request and the check runs again. The label doesn't allow a removal, a renumbering or a metric change: published icons are never removed or renumbered.

If the generated files are out of date, run npm run build on the branch and commit what it changes.

To run the check before you push:

npm ci
npm run build
git worktree add ../dot-icons-main origin/main
npm run check -- --base ../dot-icons-main
npm test

Configuring Jest

dot-icons uses @font-face which Jest/jsdom cannot process. Add a style mock:

jest.config.js

moduleNameMapper: {
  '@digital-ai/dot-icons': '<rootDir>/testing-utils/style-mock.ts',
}

testing-utils/style-mock.ts

module.exports = {};

Troubleshooting

Latest dot-icons not picked up by dot-components

Add a resolutions entry to your package.json:

"resolutions": {
  "@digital-ai/dot-icons": "latest"
}

More information: dot design system — Icons