# How the Mermaid packs were made, and how to do it again

This folder holds three Iconify packs, a classic script that carries the same data, and the demo
page. Everything except `index.html` is generated by `tools/build.mjs`.

---

## 1. The prompt

> Give the icon library to Mermaid. Register an icon pack so a diagram can name an icon as
> `databricks-color:<slug>`. Build an example page with live diagrams, and a section that draws
> every icon so a missing one is visible.
>
> The instructions must be community facing. If we can rely on assets hosted on GitHub, even
> better: nobody must download a file to start.

The last line drives the design. The packs sit on GitHub Pages, the server sends
`access-control-allow-origin: *`, so a reader pastes six lines and has a working diagram.

---

## 2. What Mermaid needs

Mermaid takes an [Iconify](https://iconify.design) JSON pack:

```json
{
  "prefix": "databricks-color",
  "icons": { "lakeflow": { "body": "<g fill=\"none\" …>…</g>" } },
  "width": 48,
  "height": 48
}
```

The `body` is the inside of the SVG, with no `<svg>` wrapper. Mermaid supplies its own wrapper.

The same geometry gives three packs:

| Pack | Source variant | Use |
|---|---|---|
| `databricks-color` | the published Databricks artwork | the default. Keeps the Lava colors |
| `databricks` | the mono variant, `fill="currentColor"` | Mermaid paints it with the text color of the diagram. For a dark theme |
| `databricks-outline` | the outline variant | each icon in a white box with a lava hairline. It holds its shape on a busy or dark canvas |

The outline body carries an explicit `fill` and `stroke` on its rectangle. The `fill="none"` on
the wrapper group does not reach it, because an attribute on the element wins.

## 3. Build

```bash
node tools/build.mjs
```

The pack entries come from the same in-memory SVG bodies that write `icons/svg/` and
`icons/svg-mono/`, so a pack can never drift from the artwork.

Four files come out:

| File | Why it exists |
|---|---|
| `databricks-color.json`, `databricks.json`, `databricks-outline.json` | the packs. Fetch them at run time |
| `databricks.js` | a classic script that sets the same three packs as globals |

`databricks.js` exists for one reason. A browser blocks `fetch()` on `file://`. The demo page must
open from disk and from the web. It loads the classic script first. It calls `fetch()` only when
the globals are missing.

---

## 4. The demo page

`mermaid/index.html` is hand-written, with one generated section. The build injects between these
two markers and touches nothing else:

```html
<!-- ALL-ICONS:START -->
<!-- ALL-ICONS:END -->
```

The build fails if the markers are missing.

That section draws all 71 icons through Mermaid itself. It is a test, not decoration: if a pack
fails to register, Mermaid draws a "?" for every icon and the page shows it. **This section found a real bug
that no unit test finds** — see trap 2 below.

`fresh()` never runs on this folder. It deletes the hand-written page.

---

## 5. Traps that cost time

1. **Duplicate SVG ids across diagrams.** `mermaid.run()` derives each SVG id from `Date.now()`.
   Two diagrams that render inside the same millisecond collide. The content of the second lands
   inside the `<svg>` of the first. Render explicitly with your own ids instead:

   ```js
   for (const [i, el] of [...document.querySelectorAll('pre.mermaid')].entries()) {
     const { svg } = await mermaid.render(`dbx-diagram-${i}`, el.textContent.trim());
     el.innerHTML = svg;
   }
   ```

2. **Every icon rendered black.** The source files rely on `fill="none"` on the root `<svg>`
   element. Mermaid supplies its own `<svg>`, which has no such default, so every shape filled
   solid. The fix is to wrap each pack body in `<g fill="none">`.

3. **A "?" in place of an icon** means the pack did not register. Almost always a blocked
   `fetch()` on `file://`.

4. **`registerIconPacks()` is your JavaScript.** It runs on a page that you control. It also runs
   in a docs site that lets you configure Mermaid, such as Docusaurus, VitePress or MkDocs. It does
   **not** run inside a GitHub README, a GitHub issue, GitLab or Kroki. Those render Mermaid
   themselves and never call your code. For them, export the diagram to SVG and commit the image.

---

## 6. Change something

| Goal | Do this |
|---|---|
| Add or fix an icon | change `tools/products.mjs`, then rebuild. The packs follow |
| Change the prose or the examples | edit `mermaid/index.html` outside the ALL-ICONS markers |
| Change the all-icons section | change the generator in `tools/build.mjs`, not the HTML |

After any change, open the page and scroll to **Every icon**. If you see a "?" or a gray box,
the pack is broken. Do not ship it.
