Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Add Loki and Figma Desktop workflows to component skill (#81763)

Stas Gavrylovace7aa5dd094
diff --git a/.claude/skills/metabase-ui-component-from-figma/SKILL.md b/.claude/skills/metabase-ui-component-from-figma/SKILL.md
index fead481fafd..ce426c6c4f6 100644
--- a/.claude/skills/metabase-ui-component-from-figma/SKILL.md
+++ b/.claude/skills/metabase-ui-component-from-figma/SKILL.md
@@ -31,6 +31,11 @@ Phases 1, 2, 5 and 6 are shared. The middle two differ in **order**: update mode
- **The component's intended API** — variants, sizes, and states the design system supports for this component. This defines the axes of your showcase (Phase 3).
3. Decide the mode (see **Two modes** above): search for an existing component — in `metabase/ui` or as a legacy component elsewhere. Found → **update**; nothing equivalent anywhere → **create**. Confirm with the user when unsure.
4. **Verify a Figma desktop MCP is connected before doing the work** — this skill depends on it for exact tokens in Phase 4 (and styling can't proceed accurately without it). Do a quick read against the issue's node (e.g. `get_metadata`/`get_variable_defs`); if it errors with "nothing selected" or the server isn't connected, prompt the user to enable it (Switch to Dev Mode → MCP section in the right sidebar) and select the relevant layer before continuing.
+5. **Figma Desktop MCP environments only:** open the issue's exact page with [`figma-open`](./figma-open) before MCP reads. Do not run this helper when Desktop MCP is unavailable.
+ ```bash
+ .claude/skills/metabase-ui-component-from-figma/figma-open "<figma-url-with-node-id>"
+ ```
+ A URL with `node-id` needs no token. Bare page-name and `--list` lookups require an already-configured `FIGMA_TOKEN`.
## Phase 2 — Understand the component
@@ -240,5 +245,6 @@ Only after sign-off:
- [ ] Storybook showcase matrix built from the component's full state space (theme excluded — global toggle drives light/dark), single panel, hover/pressed forced via `storybook-addon-pseudo-states`, controls scoped per story; lint + type-check pass. (Update mode: built before styling, **component styles untouched**. Create mode: built after the component is implemented in Phase 4.)
- [ ] Figma desktop MCP available; exact tokens extracted and mapped to semantic `--mb-color-*` (NO `color-mix`, NO primitives) and to existing scale vars for radius/spacing/elevation/type — any color *or* dimensional value with no matching token/scale step flagged to the user, not baked in as a literal.
- [ ] Component styled; stylelint + eslint(+CSS modules) + type-check pass.
+- [ ] Loki coverage registered: `storiesFilter` matches exact story display names; targeted `loki update` generated references; reference PNGs and Playwright screenshots visually inspected; targeted `loki test` passes; `.loki/reference/*.png` included in the commit.
- [ ] Iterated with the user until satisfied.
- [ ] Committed (when asked); call sites migrated/verified (update) or export wired (create); findings doc handed back.
diff --git a/.claude/skills/metabase-ui-component-from-figma/figma-open b/.claude/skills/metabase-ui-component-from-figma/figma-open
new file mode 100755
index 00000000000..b544a0b48c0
--- /dev/null
+++ b/.claude/skills/metabase-ui-component-from-figma/figma-open
@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# figma-open — open a Figma file (or a specific page) in the Figma desktop app
+#
+# Usage:
+# figma-open <url-or-file-key> open the file
+# figma-open <url-or-file-key> <node-id> open at a node/page id (e.g. 12-3 or 12:3)
+# figma-open <url-or-file-key> --list list pages with their ids
+# figma-open <url-or-file-key> "Page name" open a page by name
+#
+# Page lookup by name/--list needs a Figma personal access token:
+# export FIGMA_TOKEN=figd_... or put it in ~/.config/figma/token
+set -euo pipefail
+
+arg="${1:-}"
+[[ -n "$arg" ]] || { awk 'NR==1 && /^#!/ {next} /^#/ {sub(/^# ?/,""); print; next} {exit}' "$0"; exit 1; }
+
+token="${FIGMA_TOKEN:-}"
+[[ -f "$HOME/.config/figma/token" ]] && token="$(<"$HOME/.config/figma/token")"
+
+# Extract the file key from any Figma URL form, or use the arg as a bare key.
+key="$arg"
+case "$arg" in
+ *figma.com*|figma://*)
+ key="$(printf '%s' "$arg" | sed -E 's#https?://([a-z]+\.)?figma\.com##; s#^([a-z0-9-]+\.)?figma\.com##; s#^figma://##; s#^/?(file|design|proto|board)/##; s#^/##; s#/.*##; s#\?.*##')"
+ ;;
+esac
+
+req="${2:-}"
+
+# If no page arg was given but the URL carries a node-id, use it.
+url_node="$(printf '%s' "$arg" | sed -nE 's/.*[?&]node-id=([0-9]+([-:][0-9]+)*).*/\1/p')"
+
+open_fig() { # $1 = optional node id
+ if [[ -n "${1:-}" ]]; then
+ open "figma://file/${key}?node-id=${1//:/-}"
+ else
+ open "figma://file/${key}"
+ fi
+}
+
+# No page requested — open the file (or the node the URL points at).
+[[ -z "$req" ]] && { open_fig "${url_node:-}"; exit 0; }
+
+# Explicit node id (page ids work: pages are top-level nodes).
+if [[ "$req" =~ ^[0-9]+[:-][0-9]+$ ]]; then
+ open_fig "$req"
+ exit 0
+fi
+
+# Everything else needs the REST API.
+[[ -n "$token" ]] || { echo "error: page lookup needs FIGMA_TOKEN (env or ~/.config/figma/token)" >&2; exit 1; }
+
+pages_json="$(curl -sf -H "X-Figma-Token: ${token}" "https://api.figma.com/v1/files/${key}?depth=1")" \
+ || { echo "error: could not fetch file ${key} (bad key, no access, or bad token)" >&2; exit 1; }
+
+if [[ "$req" == "--list" || "$req" == "-l" ]]; then
+ printf '%s\n' "$pages_json" | jq -r '.document.children[] | "\(.id // .guid)\t\(.name)"' | column -t -s $'\t'
+ exit 0
+fi
+
+# Page by name (case-insensitive, exact match first, then substring).
+node_id="$(printf '%s' "$pages_json" | jq -r --arg n "$req" \
+ 'first(.document.children[] | select((.name // "") | ascii_downcase == ($n | ascii_downcase)) | .id // .guid) //
+ first(.document.children[] | select((.name // "") | ascii_downcase | contains($n | ascii_downcase)) | .id // .guid) //
+ empty')"
+
+[[ -n "$node_id" ]] || { echo "error: no page matching \"$req\" in file ${key}" >&2; exit 1; }
+open_fig "$node_id"