Skip to content

Agent skill that turns natural language, code, Terraform/K8s, SQL, OpenAPI, AsyncAPI, Protobuf and GraphQL sources into editable, tested draw.io architecture diagrams: incremental sync, multi-view projection, drift diff, CI architecture tests, whiteboard derasterize, interactive HTML/PPTX/Mermaid exports.

docs: register dbxicons in SKILL.md and the toolbox; add references/databricks.md

krzysztof-zdebffa48209798f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 734c5f1..6fdf510 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,23 @@ All notable changes to **drawio-skill** are documented here. The format is based
on [Keep a Changelog](https://keepachangelog.com/), and the project follows
semantic-ish versioning (the `version:` field in `skills/drawio-skill/SKILL.md`).
+## [Unreleased]
+### Added
+- **`scripts/dbxicons.py`** — Databricks product icon resolver, following the
+ `aiicons.py` pattern. draw.io has no Databricks shape set, so lakehouse
+ architectures rendered as generic boxes; only the bare Databricks logo
+ resolved (via the `aiicons.py` simple-icons supplement, which is unchanged).
+ Resolves 71 products from the community
+ [databricks-architecture-icons](https://github.com/oieduardorabelo/databricks-architecture-icons)
+ project (official Databricks artwork, referenced by URL — no artwork bundled,
+ trademarks of Databricks, Inc.). Former product names resolve through aliases
+ (DLT → `spark-declarative-pipelines`, Workflows → `lakeflow-jobs`, Vector
+ Search → `ai-search`), `--variant color|tile|outline`, `--embed` inlines a
+ marker-less base64 data URI fetched from a commit pinned in
+ `data/databricks-icons.json`, and `--refresh-manifest` regenerates that
+ manifest from the upstream catalog. Brand guidance (zone colors, category
+ accents, capability-node style) in `references/databricks.md`.
+
## [2.1.1] — 2026-08-23
### Fixed
- **Embed images in SVG exports** (`--embed-svg-images` in `scripts/svgflow.py`,
diff --git a/skills/drawio-skill/SKILL.md b/skills/drawio-skill/SKILL.md
index 2b10a5f..7ce6193 100644
--- a/skills/drawio-skill/SKILL.md
+++ b/skills/drawio-skill/SKILL.md
@@ -41,6 +41,7 @@ When the workflow references one of these, read it on demand — none of them ne
| `references/diagram-types.md` | The user names a specific diagram type (ERD, UML class, sequence, C4, architecture, ML/DL, flowchart, SysML, BPMN, network topology, swimlane) |
| `references/shapes.md` + `scripts/shapesearch.py` | The diagram needs a **specific shape** — a cloud icon (AWS/Azure/GCP), Cisco/Kubernetes/network symbol, UML/BPMN/ER/electrical/P&ID element — or any time you'd otherwise guess a `style=` string. `shapesearch.py "<keywords>"` returns the exact official style for 10k+ shapes |
| `scripts/aiicons.py` | The diagram involves an **AI/LLM brand** (OpenAI, Claude, Gemini, Mistral, Llama, HuggingFace, Ollama, LangChain, …) — `aiicons.py "<brand>"` returns a draw.io `image` style for the brand logo (lobe-icons via CDN; `--embed` to inline). draw.io has no built-in AI logos. See `references/shapes.md` → "AI / LLM brand logos" |
+| `scripts/dbxicons.py` | The diagram involves a **Databricks product** (Unity Catalog, Lakeflow Jobs, DLT, Databricks SQL, Mosaic AI, …) — `dbxicons.py "<product>"` returns a draw.io `image` style for the official product icon (71 products, community-hosted; `--embed` to inline). Former names resolve too (DLT, Workflows, Vector Search). draw.io has no Databricks shapes. See `references/databricks.md` |
| `references/style-presets.md` | The user asks to learn / save / list / set-default / delete a style preset, or you've resolved an active preset and need the application rules |
| `references/style-extraction.md` | You're inside the Learn flow and need the extraction procedure (called from `style-presets.md`) |
| `references/troubleshooting.md` | An export fails, vision rejects a PNG, or a rendering looks wrong |
diff --git a/skills/drawio-skill/references/databricks.md b/skills/drawio-skill/references/databricks.md
new file mode 100644
index 0000000..cdbf0a5
--- /dev/null
+++ b/skills/drawio-skill/references/databricks.md
@@ -0,0 +1,60 @@
+# Databricks Diagrams
+
+How to draw Databricks architectures with real product icons.
+
+## Resolving icons
+
+draw.io has no Databricks shape set. For **any Databricks product** (Unity
+Catalog, Lakeflow Jobs, DLT, Databricks SQL, Mosaic AI, ...), never guess a
+`shape=` or image URL — resolve it:
+
+```bash
+python3 <this-skill-dir>/scripts/dbxicons.py "unity catalog" # URL reference
+python3 <this-skill-dir>/scripts/dbxicons.py "DLT" --embed # self-contained
+python3 <this-skill-dir>/scripts/dbxicons.py --list # all 71 products
+```
+
+Renamed products resolve through aliases (DLT → `spark-declarative-pipelines`,
+Workflows → `lakeflow-jobs`, Vector Search → `ai-search`). Variants:
+`--variant color|tile|outline` (no mono — those SVGs render black in draw.io).
+For the bare Databricks company logo, `aiicons.py "databricks"` also works.
+
+**URL vs `--embed`:** the default style references the SVG from the community
+project's site, so draw.io needs network access when the diagram is rendered or
+opened. `--embed` fetches the SVG once (from a commit pinned in the manifest)
+and inlines it as a data URI — the diagram is then self-contained and needs
+network only at generation time. Prefer `--embed` for diagrams that must render
+offline or live long.
+
+## Brand-styled diagrams
+
+Zone colors (Databricks brand rule):
+
+| Zone | Color | Marks |
+| --- | --- | --- |
+| Lava | `#FF5F46` | the Databricks platform boundary |
+| Oat | `#D9D7CE` | external systems |
+| Navy | `#143D4A` | customer-owned infrastructure |
+
+Each resolved product carries its `categoryColor` (8 categories: platform
+`#FF3621`, engineering `#2272B4`, storage `#00875C`, analytics `#1B5162`, ai
+`#98102A`, governance `#1B3139`, sharing `#BA7B23`, devtools `#618794`). Use it
+as an accent — a container stroke or a label color — not as a fill behind the
+icon.
+
+Capability node (140x60, icon box with a bold label below):
+
+```
+shape=image;html=1;whiteSpace=wrap;imageAspect=1;verticalLabelPosition=bottom;verticalAlign=top;labelPosition=center;align=center;fontSize=11;fontStyle=1;fontColor=#1B3139;image=<resolved>;
+```
+
+Replace `<resolved>` with the `image=` value from `dbxicons.py` output.
+
+## Attribution
+
+Icons come from the community project
+[databricks-architecture-icons](https://github.com/oieduardorabelo/databricks-architecture-icons),
+which serves official Databricks artwork; its `drawio/` folder has the full
+brand template system. The icons are trademarks of Databricks, Inc., referenced
+for identification only. This skill bundles no artwork — only a name manifest
+(`data/databricks-icons.json`).
diff --git a/skills/drawio-skill/references/toolbox.md b/skills/drawio-skill/references/toolbox.md
index 84c2f36..2902b5b 100644
--- a/skills/drawio-skill/references/toolbox.md
+++ b/skills/drawio-skill/references/toolbox.md
@@ -37,7 +37,7 @@ exports it:
| a `.drawio` | diagrams-as-code | `drawio2mermaid` (→ Mermaid) |
| a `.drawio` | the same diagram in another language | `relabel` (extract → translate → apply) |
| a `.drawio` | it re-themed (dark / corporate preset) | `restyle` |
-| a shape/icon need | the exact style string | `shapesearch` · `aiicons` (AI/LLM logos) |
+| a shape/icon need | the exact style string | `shapesearch` · `aiicons` (AI/LLM logos) · `dbxicons` (Databricks products) |
| a photo/screenshot of a diagram | an editable `.drawio` | `raster2drawio` (your vision → JSON → draw.io) |
| ONE `.drawio` | it building itself, as a video/GIF | `buildup` (→ HTML player; `--gif`) |
| a big/sprawling diagram | a boardroom exec summary + drill-down | `compress` |
@@ -51,7 +51,7 @@ exports it:
- **`seqlayout.py`** — participants + messages JSON → sequence diagram with computed lifelines/activation bars (no Graphviz).
- **`c4.py`** — levels JSON → one multi-page `.drawio` (Context→Container→Component) with click-to-drill-down links.
- **`tubemap.py`** — metro JSON (coloured lines + grid-placed stations) → a London-Underground-style **tube map**: octilinear (H/V/45°) routing, white interchange circles, station stops. No Graphviz. See `references/tubemap.md`.
-- **`shapesearch.py`** — search 10k+ official shapes for their exact `style=` string. **`aiicons.py`** — draw.io `image` styles for AI/LLM brand logos.
+- **`shapesearch.py`** — search 10k+ official shapes for their exact `style=` string. **`aiicons.py`** — draw.io `image` styles for AI/LLM brand logos. **`dbxicons.py`** — draw.io `image` styles for Databricks product icons (see `references/databricks.md`).
- **`raster2drawio.py`** — a vision-extracted image graph JSON (from a whiteboard photo / legacy PNG / Visio screenshot) → editable `.drawio` honouring the read coordinates; missing positions fall back to `autolayout.py`. See `references/derasterize.md`.
## 2. Code → diagram