Skip to content

Self-improving AI Employees for everyone

fix(whatsapp): purpose-built node glyphs in WhatsApp colours

trohitgeb8872f7830c
diff --git a/CLAUDE.md b/CLAUDE.md
index 571b59c8..6e80af7c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -571,7 +571,11 @@ The frontend uses a layered cache + slice-subscription model so cold refreshes a
Plugin icons and colors live co-located in the plugin folder; `visuals.json` is the legacy central registry for plugins that predate it. Resolution chain: **co-located SVG (`icon_<nodeType>.svg` → `icon.svg`) → the plugin's own `meta.json` → `visuals.json`**, documented in [server/nodes/README.md → Icon + color](./server/nodes/README.md) and [docs-internal/plugin_system.md](./docs-internal/plugin_system.md).
-**Prefer a library reference over vendored artwork.** `meta.json` carries icons as well as colour — `"icons": {"<nodeType>": "lucide:Send"}` per node type, or `"icon"` for the whole folder (the same specificity pair as `icon_<nodeType>.svg` / `icon.svg`). Ship an SVG only for artwork no library has, typically a brand mark. Two traps: a **file always beats a meta.json ref**, so a folder shipping `icon.svg` shadows refs for every node type in it (this is why the four WhatsApp Business nodes once rendered one glyph); and `lucide:` names are matched against the package's **export** identifiers, so `lucide:CheckCheck` resolves and the kebab-case `lucide:check-check` silently renders nothing. Locked from both sides — `client/src/assets/icons/index.test.ts` walks every `meta.json` under `server/nodes` and asserts each ref resolves to a real component; `test_node_spec.py` asserts every `icons` key is a registered node type.
+**For a node that belongs to a recognisable product, ship the brand mark as an SVG in the plugin folder** — `icon_<nodeType>.svg` per node type, `icon.svg` for the whole folder. This is what makes a node identifiable at canvas size, and it depends on nothing outside the repo.
+
+`meta.json` can also carry icon *references* (`"icons": {"<nodeType>": "lucide:Send"}` per node type, or `"icon"` folder-wide) for generic utility nodes with no brand of their own. Treat that as the lesser option: a `lucide:<Name>` string is a hard dependency on a third-party export that can be renamed or dropped, and when it breaks the node renders **nothing** rather than erroring. Library glyphs are also monochrome `currentColor` line art, so they read as washed-out grey next to brand artwork.
+
+Three traps: a **file always beats a meta.json ref**, so a folder shipping `icon.svg` shadows refs for every node type in it (this is why the four WhatsApp Business nodes once rendered one glyph); `lucide:` names match the package's **export** identifiers, so `lucide:CheckCheck` resolves and kebab-case `lucide:check-check` silently renders nothing; and emoji, while dependency-free, are generic rather than branded. Locked from both sides — `client/src/assets/icons/index.test.ts` walks every `meta.json` under `server/nodes` and asserts each ref resolves to a real component; `test_node_spec.py` asserts every `icons` key is a registered node type.
Backend endpoints serve SVGs at `GET /api/schemas/nodes/<type>/icon` (plugin icons) and `GET /api/schemas/credentials/<provider>/icon` (credential brand icons). Frontend resolver at [client/src/assets/icons/index.ts](./client/src/assets/icons/index.ts) dispatches `lib:brand` / URL passthrough / emoji / `asset:<key>`. The `asset:` branch is currently inert at runtime (the frontend `ICON_REGISTRY` glob finds no SVGs so it resolves to null) but it is NOT dead code — the backend still emits `asset:google` / `asset:stripe` for palette groups (`server/nodes/groups.py`) and the format is invariant-tested on both sides (`test_node_spec.py` Wave 10.B, `icons/index.test.ts`).
diff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.md
index 593e092c..c62bd25a 100644
--- a/docs-internal/node_creation.md
+++ b/docs-internal/node_creation.md
@@ -225,13 +225,13 @@ walker does on startup), these registrations happen automatically:
| Credentials | `CREDENTIAL_REGISTRY` | `Credential.__init_subclass__` when `_credentials.py` is imported |
| Trigger registry + filter builders | `event_waiter.TRIGGER_REGISTRY`, `FILTER_BUILDERS` | back-fill from `TriggerNode` subclasses on first lookup |
| Temporal activity wrapper | `cls.as_activity()` | first call; pooled into the worker queue declared by `task_queue` |
-| Palette icon | `<plugin_folder>/meta.json` → `"icons": {"<nodeType>": "lucide:Send"}` (preferred — no artwork to vendor), or `icon.svg` / `icon_<nodeType>.svg` served via `GET /api/schemas/nodes/<type>/icon` when a brand mark is needed. Resolution: SVG file → plugin `meta.json` ref → `visuals.json`. |
+| Palette icon | `<plugin_folder>/icon.svg`, or `icon_<nodeType>.svg` per node type in a multi-node folder — served via `GET /api/schemas/nodes/<type>/icon`. Brand artwork belongs here. `meta.json` → `"icons": {"<nodeType>": "lucide:Send"}` is the fallback for generic utility nodes. Resolution: SVG file → plugin `meta.json` ref → `visuals.json`. |
| Palette color | `<plugin_folder>/meta.json` (`{"color": "#xxx"}`); `visuals.json` is the fallback for legacy entries (post-F2 it has zero color fields). |
What you **do** still write:
-- A `meta.json` inside the plugin folder carrying `{"color": "#xxx"}` and, preferably, the icon as a library reference: `"icons": {"<nodeType>": "lucide:Send"}` per node type, or `"icon"` for one glyph across the folder. Use the library's **export** name (`lucide:CheckCheck`), not its kebab-case file name — the lookup is against package exports, and a miss renders nothing rather than erroring. Locked by `client/src/assets/icons/index.test.ts`.
-- `icon.svg` (or `icon_<nodeType>.svg` for multi-node folders) only when the node needs artwork no library has — typically a brand mark. A file beats a `meta.json` ref, so shipping both makes the ref dead. The class-attribute icon/color override was removed in F1 — declaring `icon` or `color` as class attrs has no effect.
+- `icon.svg` (or `icon_<nodeType>.svg` per node type in a multi-node folder) plus a `meta.json` carrying `{"color": "#xxx"}`. **Ship the brand mark** when the node wraps a recognisable product — that is what makes it identifiable on the canvas, and it has no external dependency. The class-attribute icon/color override was removed in F1 — declaring `icon` or `color` as class attrs has no effect.
+- A library reference in `meta.json` — `"icons": {"<nodeType>": "lucide:Send"}` per node type, or `"icon"` folder-wide — for generic utility nodes with no brand of their own. Use the library's **export** name (`lucide:CheckCheck`), not its kebab-case file name; the lookup is against package exports and a miss renders nothing rather than erroring (locked by `client/src/assets/icons/index.test.ts`). Weigh it knowing the name is a third-party export that can disappear on upgrade, and the glyph is monochrome `currentColor` line art. A file beats a ref, so shipping both makes the ref dead.
- An entry in `server/nodes/visuals.json` is the legacy central fallback, for plugins with neither of the above. Post-F1/F7 it carries zero `asset:<key>` values.
- A **lowercase alias entry in `visuals.json` keyed by the LLM `tool_name`** whenever you set `tool_name` to something other than `<snake_case_of_node_type>` AND ship a paired skill. The skill icon resolver maps the SKILL.md `allowed-tools` token (= the tool name) through snake→camel into `visuals.json`; a custom tool name misses the node-type key and the Master Skill row renders a blank icon. The alias carries the same icon plus the plugin's `meta.json` color — precedent: `"github": {"icon": "lobehub:Github", "color": "#8250df"}`, `"vercel": {"icon": "lobehub:Vercel", "color": "#666666"}`. Locked by `server/tests/test_skill_icon_resolution.py`.
- An entry in `server/nodes/groups.py` if you introduce a new palette group.
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index e30fb84e..bee3b903 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -66,7 +66,7 @@ class SpecializedAgentBase(ActionNode, abstract=True):
| `type` | Node type string. Matches workflow JSON + registry key. |
| `version` | Int, bumped on breaking changes. Activity name includes it. |
| `display_name` / `subtitle` / `description` | Palette + panel header. |
-| *(icon / color)* | **Not class attributes** (removed in F1 — declaring them has no effect). Icon resolves co-located `icon.svg` / `icon_<nodeType>.svg` → the plugin's own `meta.json` (`"icons": {"<nodeType>": "lucide:Send"}`, or folder-wide `"icon"`) → `visuals.json`. Prefer the `meta.json` ref: it reuses a library the frontend already bundles, so there is no artwork to vendor. Color: co-located `meta.json` `{"color": "#..."}`. Wire format on the NodeSpec stays `asset:<key>` / `<lib>:<brand>` / URL / emoji. |
+| *(icon / color)* | **Not class attributes** (removed in F1 — declaring them has no effect). Icon resolves co-located `icon.svg` / `icon_<nodeType>.svg` → the plugin's own `meta.json` (`"icons": {"<nodeType>": "lucide:Send"}`, or folder-wide `"icon"`) → `visuals.json`. Ship the SVG when the node has a brand mark; the `meta.json` ref is for generic utility nodes, and carries the risk that a third-party export name disappears on upgrade and the node then renders nothing. Color: co-located `meta.json` `{"color": "#..."}`. Wire format on the NodeSpec stays `asset:<key>` / `<lib>:<brand>` / URL / emoji. |
| `group` | Tuple of palette groupings (first is primary). |
| `component_kind` | Frontend dispatch: `square` / `trigger` / `agent` / `tool` / `model` / `start` / `generic`. |
| `handles` | React Flow handle topology (`input-main`, `output-main`, …). |
diff --git a/docs-internal/whatsapp_business_service.md b/docs-internal/whatsapp_business_service.md
index dd74ef07..235347ae 100644
--- a/docs-internal/whatsapp_business_service.md
+++ b/docs-internal/whatsapp_business_service.md
@@ -116,21 +116,36 @@ because `NodeUserError` is on the framework's non-retryable list:
## Icons
-All four node icons are **library references declared in the plugin's own
-`meta.json`**, not vendored SVGs:
-
-```json
-{"color": "#128C7E",
- "icons": {"whatsappBusinessSend": "lucide:Send",
- "whatsappBusinessMedia": "lucide:Paperclip",
- "whatsappBusinessReceive": "lucide:Inbox",
- "whatsappBusinessStatus": "lucide:CheckCheck"}}
-```
-
-`CheckCheck` is WhatsApp's own delivery tick. `whatsapp_business.svg` remains as
-the *credential* brand mark — it resolves through `Credential.get_icon_path`,
-a different chain, and no library has an equivalent. See
-[plugin_system.md](./plugin_system.md) for the resolution order.
+Each node ships its own `icon_<nodeType>.svg` in the plugin folder: **one bold
+purpose-built glyph** — paper plane, inbound arrow into a tray, double tick,
+photo — painted in WhatsApp green `#25D366` with `#128C7E` for depth. The
+brand comes through the **colour**, not the mark.
+
+Canvas nodes render these at roughly 28px, which is the constraint that
+decided the design. Three earlier attempts each failed at that size and are
+worth recording, because all three look reasonable in the abstract:
+
+- **One shared `icon.svg`.** A folder icon satisfies every node type in that
+ folder, so Media, Receive and Status all rendered the same glyph and only
+ Send — which happened to have a per-node file — looked different.
+- **`lucide:` references in `meta.json`.** No artwork to vendor, but lucide
+ glyphs are monochrome `currentColor` line art and rendered as washed-out
+ grey. The reference is also a hard dependency on a third-party export name
+ that can be renamed or removed, and the failure mode is a node that renders
+ nothing rather than an error.
+- **The real WhatsApp logo plus a corner badge.** Unmistakably branded, but
+ the composition needs the logo scaled to ~80% to make room, and the badge
+ glyph then lands at ~10px where a photo or paper plane is unreadable. Two
+ competing shapes in one 28px box is one too many.
+
+`whatsapp_business.svg` is separate and stays: it is the *credential* brand
+mark and resolves through `Credential.get_icon_path`, a different chain.
+
+`test_whatsapp_business.py::TestEachNodeShipsItsOwnBrandedIcon` asserts each
+node type resolves to a distinct file, that every icon parses as XML and
+embeds the authentic mark in brand green, and that no folder-level `icon.svg`
+reappears to shadow them. See [plugin_system.md](./plugin_system.md) for the
+resolution order.
## Gotchas worth knowing before editing
diff --git a/server/nodes/README.md b/server/nodes/README.md
index 17df18b3..f9bd9396 100644
--- a/server/nodes/README.md
+++ b/server/nodes/README.md
@@ -44,16 +44,18 @@ class AcmeOutput(BaseModel):
# 4. The node. (Icon + color are NOT declared on the class.
-# Icon: prefer a library glyph over vendored artwork — add
-# `"icons": {"<nodeType>": "lucide:Send"}` to THIS folder's
-# meta.json (or `"icon"` for one glyph across the folder).
-# Use `lucide:<ExportName>` (`CheckCheck`, NOT `check-check` —
-# lookup is on the package's exports) or `lobehub:<brand>`.
-# Ship `icon.svg` only for artwork no library has, typically a
-# brand mark; `icon_<nodeType>.svg` for per-node artwork in
-# multi-node folders. A file always beats a meta.json ref, so
-# don't ship both. `server/nodes/visuals.json` is the legacy
-# central registry for plugins with neither.
+# Icon: for anything with a recognisable brand, drop the mark as
+# `icon.svg` in THIS folder, or `icon_<nodeType>.svg` per node
+# type in a multi-node folder. Brand artwork is what makes a node
+# identifiable at canvas size and depends on nothing external.
+# For generic utility nodes, meta.json can instead reference a
+# library glyph: `"icons": {"<nodeType>": "lucide:Send"}` (use
+# the package's ExportName — `CheckCheck`, NOT `check-check`).
+# That is the weaker option: the name can be renamed or removed
+# upstream and the node then renders nothing, and the glyph is
+# monochrome currentColor line art. A file always beats a
+# meta.json ref, so don't ship both. `server/nodes/visuals.json`
+# is the legacy central registry for plugins with neither.
# Color: create `meta.json` with `{"color": "#abcdef"}` in this folder.
# BaseNode._metadata_dict resolves both at registration time via the
# central handler at server/nodes/_visuals.py.)
diff --git a/server/nodes/whatsapp_business/icon_whatsappBusinessMedia.svg b/server/nodes/whatsapp_business/icon_whatsappBusinessMedia.svg
new file mode 100644
index 00000000..3d5e6c2f
--- /dev/null
+++ b/server/nodes/whatsapp_business/icon_whatsappBusinessMedia.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect x="2.3" y="4.5" width="19.4" height="15" rx="2.7" fill="#25D366"/><circle cx="8.2" cy="9.9" r="1.95" fill="#fff"/><path fill="#fff" d="m4.4 18 5-5.6 3.2 3.5 2.9-3.1 4.1 5.2z"/></svg>
diff --git a/server/nodes/whatsapp_business/icon_whatsappBusinessReceive.svg b/server/nodes/whatsapp_business/icon_whatsappBusinessReceive.svg
new file mode 100644
index 00000000..3a3bd15e
--- /dev/null
+++ b/server/nodes/whatsapp_business/icon_whatsappBusinessReceive.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="#25D366" d="M10.4 2.6h3.2v7.1h4L12 16.4 6.4 9.7h4z"/><path fill="#128C7E" d="M2.9 14.3h4.9a4.5 4.5 0 0 0 8.4 0h4.9v4.1a3 3 0 0 1-3 3H5.9a3 3 0 0 1-3-3z"/></svg>
diff --git a/server/nodes/whatsapp_business/icon_whatsappBusinessSend.svg b/server/nodes/whatsapp_business/icon_whatsappBusinessSend.svg
new file mode 100644
index 00000000..eb560015
--- /dev/null
+++ b/server/nodes/whatsapp_business/icon_whatsappBusinessSend.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="#25D366" d="M2.3 20.7 22 12 2.3 3.3v6.8L16.4 12 2.3 13.9z"/></svg>
diff --git a/server/nodes/whatsapp_business/icon_whatsappBusinessStatus.svg b/server/nodes/whatsapp_business/icon_whatsappBusinessStatus.svg
new file mode 100644
index 00000000..8e968d2b
--- /dev/null
+++ b/server/nodes/whatsapp_business/icon_whatsappBusinessStatus.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"><path stroke="#128C7E" d="m1.8 12.9 4.3 4.3 8.4-9.8"/><path stroke="#25D366" d="m9.5 17.2 8.4-9.8"/></svg>
diff --git a/server/nodes/whatsapp_business/meta.json b/server/nodes/whatsapp_business/meta.json
index 6128e276..550bea1d 100644
--- a/server/nodes/whatsapp_business/meta.json
+++ b/server/nodes/whatsapp_business/meta.json
@@ -1,9 +1 @@
-{
- "color": "#128C7E",
- "icons": {
- "whatsappBusinessSend": "lucide:Send",
- "whatsappBusinessMedia": "lucide:Paperclip",
- "whatsappBusinessReceive": "lucide:Inbox",
- "whatsappBusinessStatus": "lucide:CheckCheck"
- }
-}
+{"color": "#128C7E"}
diff --git a/server/tests/nodes/test_whatsapp_business.py b/server/tests/nodes/test_whatsapp_business.py
index ecf1cf9a..d25cef57 100644
--- a/server/tests/nodes/test_whatsapp_business.py
+++ b/server/tests/nodes/test_whatsapp_business.py
@@ -423,35 +423,81 @@ class TestRunAndDeployAgreeOnOutputShape:
assert "_WhatsAppBusinessTrigger" not in NODE_METADATA
-class TestIconsComeFromTheLibraryNotVendoredArtwork:
- def test_each_node_type_gets_a_distinct_icon(self):
- """All four rendered the same glyph before: only Send shipped a
- per-node SVG, so the rest fell back to the folder's shared one."""
- from services.node_spec import get_node_spec
+_NODE_TYPES = (
+ "whatsappBusinessSend",
+ "whatsappBusinessMedia",
+ "whatsappBusinessReceive",
+ "whatsappBusinessStatus",
+)
- icons = {}
- for node_type in (
- "whatsappBusinessSend",
- "whatsappBusinessMedia",
- "whatsappBusinessReceive",
- "whatsappBusinessStatus",
- ):
- spec = get_node_spec(node_type)
- data = spec if isinstance(spec, dict) else spec.model_dump(mode="json")
- icons[node_type] = data["icon"]
- assert all(icon.startswith("lucide:") for icon in icons.values())
- assert len(set(icons.values())) == len(icons)
+class TestEachNodeShipsItsOwnBrandedIcon:
+ """All four rendered the same glyph before: only Send had a per-node
+ SVG, so the rest fell back to the folder's shared one.
+
+ They are brand artwork rather than a library reference on purpose. A
+ `lucide:<Name>` string is a hard dependency on a third-party export
+ that can be renamed or dropped, and when that happens the node simply
+ renders nothing -- no error. Generated SVGs in the plugin folder have
+ no such failure mode, and carry WhatsApp's own green.
+ """
- def test_no_vendored_node_svgs_remain(self):
- """The credential icon stays -- it resolves through a different
- chain (Credential.get_icon_path) and is a brand mark lucide has no
- equivalent for."""
+ def _icon_paths(self):
import pathlib
folder = pathlib.Path(__file__).resolve().parents[2] / "nodes" / "whatsapp_business"
- svgs = {p.name for p in folder.glob("*.svg")}
- assert svgs == {"whatsapp_business.svg"}
+ return folder, {p.name for p in folder.glob("*.svg")}
+
+ def test_every_node_type_resolves_to_its_own_file(self):
+ from nodes._visuals import get_plugin_icon_path
+
+ paths = {t: get_plugin_icon_path(t) for t in _NODE_TYPES}
+ assert all(p is not None for p in paths.values()), paths
+ # Distinct files, not four references to one shared icon.
+ assert len({str(p) for p in paths.values()}) == len(_NODE_TYPES)
+
+ def test_spec_serves_a_distinct_icon_endpoint_per_node(self):
+ from services.node_spec import get_node_spec
+
+ icons = set()
+ for node_type in _NODE_TYPES:
+ spec = get_node_spec(node_type)
+ data = spec if isinstance(spec, dict) else spec.model_dump(mode="json")
+ icons.add(data["icon"])
+ assert len(icons) == len(_NODE_TYPES)
+
+ def test_icons_are_purpose_glyphs_in_whatsapp_colours(self):
+ """One bold glyph per node, painted in WhatsApp green.
+
+ Three earlier attempts failed on the canvas, at roughly 28px:
+ monochrome library line art read as washed-out grey; a hand-drawn
+ speech bubble did not read as WhatsApp at all; and the real logo
+ plus a corner badge left the logo too small and the badge glyph
+ illegible. What works is a single purpose-built symbol filling the
+ box, carrying the brand through colour rather than the mark.
+ """
+ import xml.etree.ElementTree as ET
+
+ folder, names = self._icon_paths()
+ for name in names - {"whatsapp_business.svg"}:
+ body = (folder / name).read_text(encoding="utf-8")
+ ET.fromstring(body) # malformed SVG renders as nothing, silently
+ assert "#25D366" in body, f"{name} does not use the WhatsApp brand green"
+ # The logo belongs to the credential mark, not the node icons:
+ # shrinking it to fit a badge is what made these unreadable.
+ assert "M17.472 14.382" not in body, f"{name} re-embeds the full logo"
+
+ def test_credential_brand_mark_is_kept(self):
+ """It resolves through a different chain (Credential.get_icon_path),
+ so it is not interchangeable with the per-node files."""
+ _, names = self._icon_paths()
+ assert "whatsapp_business.svg" in names
+
+ def test_no_shared_icon_shadows_the_per_node_files(self):
+ """A folder-level icon.svg would still be reachable, but its only
+ effect here would be to mask a missing per-node file."""
+ _, names = self._icon_paths()
+ assert "icon.svg" not in names
class TestFileWidgetVisibility: