chore(figma): Code Connect for 11 main components (WC + React) [DRAFT — do not merge]

.gitignore

@@ -30,6 +30,7 @@ npm-debug.log
 # Ignore Mac files
 .DS_Store
 
+.claude/playwright-*
 # Ignore Visual Studio project and settings files
 *.sln
 *.suo

packages/main/FIGMA_CODE_CONNECT_FINDINGS.md

@@ -0,0 +1,155 @@
+# Figma Code Connect — what doesn't work / what's assumed
+
+## How to connect a component (setup + runbook)
+
+**Figma file:** SAP Web UI Kit — fileKey `SILcWzK5uFghKun9jx6D7c`.
+**Everything below runs from `packages/main`.**
+
+### One-time setup
+
+**1. Clone the repo and install** (from the repo root):
+```
+git clone https://github.com/UI5/webcomponents.git
+cd webcomponents
+yarn                       # installs all workspace deps
+```
+> On the branch that carries this Code Connect work, `@figma/code-connect` and the
+> config files are already present (skip steps 2–3). On a clean `main` checkout
+> they are **not** — do steps 2–3 first.
+
+**2. Add the Code Connect dependency** to `packages/main` (only if not already there):
+```
+cd packages/main
+yarn add -D @figma/code-connect        # this repo uses ^1.4.9
+```
+
+**3. Create the two config files** in `packages/main`, one per label:
+
+`figma.config.json` (Web Components):
+```jsonc
+{ "codeConnect": {
+    "include": ["src/**/*.figma.ts"], "exclude": ["node_modules/**", "dist/**"],
+    "parser": "html", "label": "Web Components" } }
+```
+`figma.config.react.json` (React):
+```jsonc
+{ "codeConnect": {
+    "include": ["src/**/*.figma.tsx"], "exclude": ["node_modules/**", "dist/**"],
+    "parser": "react", "label": "React" } }
+```
+
+**4. Generate a Figma token:** figma.com → **profile → Settings → Security →
+Personal access tokens → Generate**. Scope: file content read/write for Code
+Connect. Keep it out of git; pass it inline (`FIGMA_ACCESS_TOKEN=…`) or export it.
+
+### Per component
+
+**5. Create the two mapping files** in `packages/main/src/`:
+- `src/<Name>.figma.ts` (Web Components) and `src/<Name>.figma.tsx` (React) —
+  each a single `figma.connect(<node-url>, { props, example })`.
+- Get the node id from the Figma URL (`?node-id=1-2` → `1:2`). To scaffold a
+  starter pre-filled with the node's readable props:
+  ```
+  FIGMA_ACCESS_TOKEN=<token> npx figma connect create "<node-url>" --outDir /tmp/cc
+  ```
+
+**6. Dry-run** (no token — catches parser errors):
+```
+npx figma connect publish --dry-run -c figma.config.json
+npx figma connect publish --dry-run -c figma.config.react.json
+```
+
+**7. Publish** (needs the token; run from `packages/main`):
+```
+FIGMA_ACCESS_TOKEN=<token> npx figma connect publish -c figma.config.json --force
+FIGMA_ACCESS_TOKEN=<token> npx figma connect publish -c figma.config.react.json --force
+```
+- `--force` overwrites any pre-existing (UI-created) mapping on the node.
+- ⚠️ MUST run from `packages/main` — from the repo root the CLI can't find the
+  config and silently falls back to the html parser. Always confirm the output
+  says `Using label "React"` (not "Web Components") for the React publish.
+
+**8. Verify in Figma Dev Mode** — parsing/upload success ≠ correct output. Open
+the node, check the real snippet under each framework label.
+
+**Connected so far (11, both WC + React):**
+Button `91702:11733` · Input `148569:1004` · CheckBox `154589:905` ·
+RadioButton `154597:1967` · StepInput `148569:1727` · MessageStrip `910:2517` ·
+Select `181557:7507` · SegmentedButton `91702:11986` · Switch `24087:10369` ·
+Link `187:305` · Avatar `573:3623`.
+(Icon `983:5876` is unpublishable — a plain frame, not a component set.)
+
+## ⚠️ Global: reading the swapped icon (nuanced — tested)
+In Figma an icon is an **INSTANCE_SWAP** property — the designer swaps in an icon
+*component* from the library. What Code Connect can and can't do with it:
+
+- **As a name STRING → NO.** `figma.string`/`figma.enum` cannot read which
+  component was swapped in. So attribute-style icons (`icon="globe"`, `endIcon=`,
+  `fallback-icon=`) can't be made dynamic this way and stay **hardcoded**
+  placeholders (`"globe"`, `"inspect"`, `"home"`, `"employee"`); consumer edits.
+- **As an ELEMENT via `figma.instance()` → YES, conditionally.** If the icon
+  library is **Code-Connected** (each icon emits `<ui5-icon name="…">`) AND the
+  host's icon instance carries a `mainComponent` link, `figma.instance("Icon")`
+  resolves the **selected** icon's element. **Tested:** ✅ worked on Button
+  (`<ui5-icon name="globe">` resolved); ❌ empty on MessageStrip (its instance
+  had no `mainComponent` link). Only fits **slot/child** placements — its output
+  is an element, not a bare string, so it still can't feed an `icon=` attribute.
+
+**Owner fixes:** (a) add an `Icon Name` **text property** alongside the swap →
+`figma.string` reads it → works for the attribute cases; (b) **Code-Connect the
+icon library** (generated, ~1400 entries) → `figma.instance` resolves the
+element for slot cases on link-carrying hosts.
+
+
+## 1. Button — ui5-button (node 91702:11733)
+**Doesn't work:**
+- badge `text` — **HARDCODED `"72"`, NOT read from Figma.** The count is in an unexposed nested layer; the snippet always emits `text="72"` and won't track the Figma number. *Owner fix: expose the count as a readable text prop.*
+
+
+**Assumed (design rule):**
+- badge `design` ← Form Factor: Compact → InlineText, Cozy → OverlayText (per kit owners). *Confirm by toggling Form Factor with a counter badge on.*
+
+
+## 2. Input — ui5-input (node 148569:1004)
+**Doesn't work:**
+- `Content` (Placeholder vs Typed Text) — Figma-only display toggle; can't gate which text emits, so both `value` and `placeholder` are always emitted.
+
+## 3. Select — ui5-select (node 181557:7507)
+**Doesn't work:**
+
+-`options` → placeholder options
+
+  What: The generated <ui5-select> always shows generic <ui5-option>Option 1/2/3</ui5-option>,
+  never the real dropdown choices from the design.
+
+  Why: Options are slotted children (same as SegmentedButton labels). In Figma the Select is
+  drawn as a closed control — it's essentially an embedded Input showing the selected text,
+  with no readable list of the option values behind it. So there's nothing to read → fixed
+  placeholders.
+
+- `Drop-Down` (True/False) → Figma-only runtime open state
+
+  Figma has a Drop-Down variant (closed vs open-showing-the-list). But "open/closed" is a
+  runtime interaction state, not a component property in code — you don't write <ui5-select
+  open> as a design intent. So there's nothing meaningful to emit from it; it's a Figma-only
+  concept.
+
+
+## 4. SegmentedButton — ui5-segmented-button (node 91702:11986)
+
+**Doesn't work:**
+
+- segment `labels` — the item text ("Option 1"…) lives in Figma slots (⿻ Text Segments),
+  which are light-DOM projection, not a readable property. So real labels can't be read →
+  placeholders. (Different from the icon issue: this is slotted content, not instance-swap.)
+- selected `segment` — which segment is pressed isn't exposed as a readable prop at all, so I
+  just mark item 1 selected as a stand-in — it won't match the actually-selected one in the
+  design.
+
+
+## 5. Avatar — ui5-avatar (node 573:3623)
+**Doesn't work:**
+- `image` slot — slotted image, not readable.
+- `badge` slot ← Badge boolean — presence only, not content.
+
+

packages/main/FIGMA_ICON_NAME_PROPOSAL.md

@@ -0,0 +1,86 @@
+# Proposal: make icon names readable in Code Connect (SAP Web UI Kit)
+
+**Audience:** SAP Web UI Kit Figma owners + webcomponents/tooling team
+**File:** SAP Web UI Kit, `SILcWzK5uFghKun9jx6D7c`
+**Date:** 2026-08-13
+
+## The problem
+
+Several components' Code Connect mappings (Button, Link, StepInput, Avatar,
+SegmentedButton, MessageStrip) can detect that an icon is **present** — and often
+**where** it sits (Link's Icon Position, Avatar's Type=Icon) — but they **cannot
+emit which icon it is**. Every `icon=` / `endIcon=` / `fallback-icon=` in the
+generated snippets is a **hardcoded placeholder** (`"globe"`, `"inspect"`,
+`"home"`, `"employee"`, `"information"`) that the consumer must edit by hand.
+
+### Why (root cause)
+
+In Figma an icon is an **INSTANCE_SWAP** property — the designer swaps in an icon
+*component* from the icon library. Code Connect's mapping primitives are:
+
+`figma.string` (reads a **text** property) · `figma.boolean` · `figma.enum`
+(fixed lookup over known variant options) · `figma.instance` · `figma.children`
+· `figma.textContent` · `figma.nestedProps`.
+
+**None of them return "the name of the component currently swapped into an
+instance-swap slot" as a string.** The name is visible in Figma's UI and exists
+as instance metadata (`mainComponentName`), but it is not exposed to the mapping
+author through any `figma.*` call. `figma.string` only reads text fields, and the
+icon is not a text field. So the mapping can toggle the attribute on/off but must
+hardcode the value.
+
+## Two fixes (complementary)
+
+### Option A — add an `Icon Name` text property  → **Figma owner, quick win**
+
+On each component that has an icon instance-swap, add a plain **text property**
+(e.g. `Icon Name`) holding the icon's registry name. The mapping then reads it:
+
+```ts
+icon: figma.string("Icon Name")   // → icon="employee" dynamically
+```
+
+- **Pro:** trivial, pure Figma-side, unlocks dynamic icon names immediately.
+- **Con:** duplicated data — the designer must keep the typed name in sync with
+  the icon actually swapped in, so it can drift.
+
+### Option B — Code-Connect the icon library  → **webcomponents/tooling team, durable**
+
+Give **each icon component** in the kit its own tiny Code Connect entry whose only
+output is its own registry name. Then, on any host component:
+
+```ts
+icon: figma.instance("Icon")   // resolves to the SELECTED icon's name
+```
+
+because `figma.instance` resolves a swapped instance **through that instance's own
+Code Connect entry**.
+
+- **This is generated, not hand-written.** The kit already names each icon
+  instance by its icon (`mainComponentName: "information"`), and the icons package
+  already has the full name registry. A script iterates the icon set and emits one
+  `figma.connect()` per icon (each outputting its name), using the icon library's
+  Figma node IDs (from the Figma API).
+- **Pro:** correct forever, zero designer effort, no drift.
+- **Con:** ~1400 published connections (one-time), needs the icon library node IDs,
+  re-run the generator when the icon set changes.
+
+**Can we drive this from our own `@ui5/webcomponents-icons` package?** Yes — that
+package is the source of truth for icon names, so it's the natural input to the
+generator in Option B. The only Figma-side dependency is the mapping from each
+icon name to its Figma component node ID, which the Figma API provides.
+
+## Recommendation
+
+- **Option A now** — one text property per component, immediate dynamic icons.
+- **Option B as the durable solution** — generated from `@ui5/webcomponents-icons`,
+  owned by the webcomponents team, no drift.
+
+Until either lands, icon **presence/position** is mapped but the **name** is a
+placeholder the consumer edits.
+
+## Same class of issue (for context)
+
+The badge **count** on Button (`text="72"`) is hardcoded for the same reason — it
+lives in an unexposed nested layer, not a readable property. Exposing it as a
+`Badge Count` text property (like Option A) would make it dynamic too.

packages/main/figma.config.json

@@ -0,0 +1,8 @@
+{
+  "codeConnect": {
+    "include": ["src/**/*.figma.ts"],
+    "exclude": ["node_modules/**", "dist/**"],
+    "parser": "html",
+    "label": "Web Components"
+  }
+}

packages/main/figma.config.react.json

@@ -0,0 +1,8 @@
+{
+  "codeConnect": {
+    "include": ["src/**/*.figma.tsx"],
+    "exclude": ["node_modules/**", "dist/**"],
+    "parser": "react",
+    "label": "React"
+  }
+}

packages/main/package.json

@@ -65,6 +65,7 @@
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.10.10",
+    "@figma/code-connect": "^1.4.9",
     "@ui5/cypress-internal": "0.1.0",
     "@ui5/webcomponents-tools": "2.25.0-rc.0",
     "cypress": "15.18.1",

packages/main/src/Avatar.figma.ts

@@ -0,0 +1,84 @@
+/**
+ * Web Components Code Connect mapping for the SAP Web UI Kit "Avatar".
+ * Node: 573:3623. Emits <ui5-avatar>.
+ *
+ * See FIGMA_CODE_CONNECT_FINDINGS.md § Avatar. Pseudo-states ignored.
+ */
+import figma, { html } from "@figma/code-connect/html";
+
+figma.connect(
+  "https://www.figma.com/design/SILcWzK5uFghKun9jx6D7c/SAP-Web-UI-Kit?node-id=573-3623",
+  {
+    props: {
+      // Size → size (1:1).
+      size: figma.enum("Size", {
+        XS: 'size="XS"',
+        S: 'size="S"',
+        M: 'size="M"',
+        L: 'size="L"',
+        XL: 'size="XL"',
+      }),
+      // Color axis → color-scheme. 1..10 → Accent1..Accent10; Transparent/
+      // Placeholder map 1:1; Image/Tile have no color-scheme equivalent.
+      colorScheme: figma.enum("Color", {
+        "1": 'color-scheme="Accent1"',
+        "2": 'color-scheme="Accent2"',
+        "3": 'color-scheme="Accent3"',
+        "4": 'color-scheme="Accent4"',
+        "5": 'color-scheme="Accent5"',
+        "6": 'color-scheme="Accent6"',
+        "7": 'color-scheme="Accent7"',
+        "8": 'color-scheme="Accent8"',
+        "9": 'color-scheme="Accent9"',
+        "10": 'color-scheme="Accent10"',
+        Transparent: 'color-scheme="Transparent"',
+        Placeholder: 'color-scheme="Placeholder"',
+        Image: "",
+        Tile: "",
+      }),
+      // Content → shape. Person → Circle, Object → Square.
+      // VERIFIED by screenshot of node 573:3623: Person column renders circles,
+      // Object column renders squares. NOTE misalignment: in Figma shape is
+      // COUPLED to Content (content source), but in the WC `shape` is an
+      // INDEPENDENT prop — Figma can't express e.g. a square person avatar.
+      shape: figma.enum("Content", {
+        Person: 'shape="Circle"',
+        Object: 'shape="Square"',
+      }),
+      // Interaction State = Disabled → disabled.
+      disabled: figma.enum("Interaction State", {
+        Disabled: "disabled",
+        Regular: "",
+        Hover: "",
+        Active: "",
+        "Toggled Hover": "",
+      }),
+      // Initials text — the Figma Initials layer only exists on Type=Initials
+      // variants, so this resolves empty (attribute omitted) on Image/Icon.
+      initials: figma.string("✏️ Initials"),
+      // Type=Icon → icon="employee" (WC default). Icon NAME is a placeholder —
+      // Person/Object Icon are instance-swaps, not readable. Emitted only for
+      // the Icon type.
+      icon: figma.enum("Type", {
+        Icon: 'icon="employee"',
+        Image: "",
+        Initials: "",
+      }),
+      // Type=Image → slotted <img> with a placeholder URL (the actual image
+      // fill isn't readable). Consumer swaps the src.
+      image: figma.enum("Type", {
+        Image: html`<img src="https://via.placeholder.com/48" />`,
+        Icon: "",
+        Initials: "",
+      }),
+      // Badge boolean → slotted <ui5-avatar-badge> with placeholder icon="edit"
+      // (badge content isn't readable — presence only).
+      badge: figma.boolean("Badge", {
+        true: html`<ui5-avatar-badge slot="badge" icon="edit"></ui5-avatar-badge>`,
+        false: "",
+      }),
+    },
+    example: ({ size, colorScheme, shape, disabled, initials, icon, image, badge }) =>
+      html`<ui5-avatar ${size} ${shape} ${colorScheme} ${disabled} ${icon} initials="${initials}">${image}${badge}</ui5-avatar>`,
+  }
+);