feat: resolve Button/Buttons Figma naming gap via alias file, not caller-side normalization

CodeConnectRegistry.resolve("Buttons", ...) returned None even though the
mapping exists under "Button" -- blend-design-system's figma.connect() call
uses the code identifier "Button", but the real published Figma component
set is named "Buttons" (plural, confirmed via Figma Desktop's Inspect
panel). figma/figmaComponentAliases.mjs records verified Figma-display-name
aliases and generate-figma-code-connect.mjs folds them into extra resolve
patterns, so a consumer never has to hand-normalize Figma names itself.
Kept separate from figma/componentMaps/*.mjs so figma:sync never overwrites
it (sync only knows blend's code identifier, not Figma's display name).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: jagguji

figma/README.md

@@ -196,7 +196,7 @@ Add `@juspay/rescript-blend` as a dependency, then call `toProps` directly
 wrapper/state composition exactly as it already is:
 
 ```rescript
-| "Buttons" =>
+| "Button" =>
   (JuspayRescriptBlend.ButtonCodeConnect.toProps(componentProps), "Blend.Button", "")
   ->convertPropsNodeStateVariable("")
 ```
@@ -225,7 +225,7 @@ nested icon instances.
 
 ### CodeConnectRegistry: no per-component code at all
 
-The `| "Buttons" => ...` switch above still has to be hand-written per
+The `| "Button" => ...` switch above still has to be hand-written per
 component, one arm per synced map -- the same duplication `toProps`
 already removed for property mappings, one level up for components.
 `src/Figma/CodeConnectRegistry.res` (generated alongside every other
@@ -246,19 +246,27 @@ edits -- no new switch arm to add. `resolve` returns
 still supplies its own tag prefix (`"Blend." ++ codeComponent` above) and
 composition, exactly like `~tagName` on `fromFigmaProps`.
 
-**Important naming caveat**, spelled out in the generated file's header
-too: `figmaComponentName` is whatever identifier blend-design-system's own
-`.figma.tsx` uses in its `figma.connect(<ComponentName>, ...)` call -- **not
-necessarily the literal name shown in Figma's layers/Inspect panel.** These
-can differ: Button's real Figma component set is named **"Buttons"**
-(plural, confirmed via Figma Desktop's Inspect panel), while blend's
-`figma.connect()` call uses the React identifier **"Button"** (singular) --
-so `resolve("Buttons", ...)` returns `None` even though a real mapping
-exists under the key `"Button"`. Reconciling a live Figma node's actual
-component name against this registry's keys (e.g. juspay-portal's existing
-`^ComponentName \d+$` instance-suffix normalization would need extending to
-handle plural/singular or other divergent names) is the caller's problem --
-this package only supplies the mapping, not Figma-node-name resolution.
+**Naming caveat, and how it's handled:** `figmaComponentName` is whatever
+identifier blend-design-system's own `.figma.tsx` uses in its
+`figma.connect(<ComponentName>, ...)` call -- **not necessarily the literal
+name shown in Figma's layers/Inspect panel.** These can differ: Button's
+real Figma component set is named **"Buttons"** (plural, confirmed via
+Figma Desktop's Inspect panel), while blend's `figma.connect()` call uses
+the React identifier **"Button"** (singular).
+
+Rather than push that reconciliation onto every caller, it's handled here:
+`figma/figmaComponentAliases.mjs` records known Figma-display-name ↔
+code-identifier divergences (each one verified against the real Figma
+component, never guessed), and `scripts/generate-figma-code-connect.mjs`
+folds them into extra `resolve` patterns automatically --
+`resolve("Buttons", ...)` and `resolve("Button", ...)` both hit the same
+arm. This file is separate from `figma/componentMaps/*.mjs` specifically so
+`figma:sync` never overwrites it (sync only knows blend's code identifier,
+never Figma's own display name). A caller can pass a raw Figma
+component/layer name straight through with zero normalization of its own;
+if `resolve` returns `None` for a name you know is really one of the synced
+components, the fix is a new entry in `figmaComponentAliases.mjs` here, not
+a normalization step in the caller.
 
 Scope: prop-mapped components only, same as `toProps`/`fromFigmaProps` --
 anything that needs to walk children (Modal/Table/Snackbar-style

figma/figmaComponentAliases.mjs

@@ -0,0 +1,29 @@
+// Manually-curated aliases: additional raw Figma component/component-set
+// names that should resolve to the same CodeConnectRegistry entry as the
+// figmaComponentName already synced into figma/componentMaps/<Component>.mjs.
+//
+// This file is NOT touched by scripts/sync-figma-code-connect.mjs and never
+// will be -- that script only knows the identifier blend-design-system's own
+// figma.connect(<Identifier>, ...) call uses (e.g. "Button"), which is a code
+// identifier, not necessarily the literal name Figma's own Inspect panel
+// shows for that component/component-set. Where the two differ, record it
+// here so a caller never has to hand-normalize the raw Figma name itself
+// before calling CodeConnectRegistry.resolve -- keeping that knowledge here
+// (and re-synced/regenerated automatically into the registry) is what lets
+// consumers avoid writing or maintaining any mapping of their own.
+//
+// Each entry must be verified against the real Figma component (Figma
+// Desktop's Inspect panel, or the Figma REST API) -- not guessed. An
+// unverified alias risks silently misrouting a real Figma layer name that
+// happens to coincide with blend's own naming.
+//
+// Keyed by componentName (the figma/componentMaps/<componentName>.mjs
+// filename, e.g. "Button"), value is an array of extra raw Figma names.
+
+export default {
+  // blend-design-system's Button.figma.tsx calls figma.connect(Button, ...)
+  // -- the code identifier is "Button" (singular). The actual published
+  // Figma component set is named "Buttons" (plural), confirmed via Figma
+  // Desktop's Inspect panel on the real published component.
+  Button: ["Buttons"],
+};

scripts/generate-figma-code-connect.mjs

@@ -39,6 +39,7 @@ import { dirname, join, basename } from "node:path";
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const MAPS_DIR = join(ROOT, "figma", "componentMaps");
 const OUT_DIR = join(ROOT, "src", "Figma");
+const ALIASES_PATH = join(ROOT, "figma", "figmaComponentAliases.mjs");
 
 function renderEnumExtraction(varName, spec) {
   const cases = Object.entries(spec.values)
@@ -180,7 +181,13 @@ let fromFigmaProps = (props: CodeConnectUtils.figmaProps, ~tagName: string="Jusp
 // removed for property mappings, one level up for components). One arm
 // per component actually generated -- an unverified scaffold never leaks
 // in, same gate as everywhere else.
-async function writeRegistry(generated) {
+//
+// `aliases` (from figma/figmaComponentAliases.mjs) supplies extra raw Figma
+// names that should match the same arm -- see that file for why this can't
+// be derived from blend-design-system's own *.figma.tsx (it only knows the
+// code identifier it was given, not necessarily the literal name Figma's
+// own Inspect panel shows for that component/component-set).
+async function writeRegistry(generated, aliases) {
   const registryPath = join(OUT_DIR, "CodeConnectRegistry.res");
   if (generated.length === 0) {
     if (existsSync(registryPath)) {
@@ -191,10 +198,11 @@ async function writeRegistry(generated) {
   }
 
   const arms = generated
-    .map(
-      (r) =>
-        `  | "${resStringLiteral(r.figmaComponentName)}" => Some((${r.componentName}CodeConnect.toProps(props), "${resStringLiteral(r.codeComponent)}"))`,
-    )
+    .map((r) => {
+      const names = [r.figmaComponentName, ...(aliases[r.componentName] ?? [])];
+      const patterns = names.map((n) => `"${resStringLiteral(n)}"`).join(" | ");
+      return `  | ${patterns} => Some((${r.componentName}CodeConnect.toProps(props), "${resStringLiteral(r.codeComponent)}"))`;
+    })
     .join("\n");
 
   const source = `// GENERATED by scripts/generate-figma-code-connect.mjs. Do not edit by hand.
@@ -206,15 +214,10 @@ async function writeRegistry(generated) {
 // IMPORTANT: figmaComponentName is whatever identifier blend-design-system's
 // own *.figma.tsx uses in its figma.connect(<ComponentName>, ...) call --
 // NOT necessarily the literal name shown in Figma's layers/Inspect panel.
-// These can differ: Button's real Figma component set is named "Buttons"
-// (plural, confirmed via Figma Desktop's Inspect panel), while blend's
-// figma.connect() call uses the React identifier "Button" (singular), so
-// this registry's "Button" key won't match a raw Figma layer name of
-// "Buttons" without the caller normalizing first (same idea as
-// juspay-portal's existing ^ComponentName \\d+$ instance-suffix
-// normalization). Resolving the actual Figma component name from a live
-// node, and reconciling it against this registry's keys, is the caller's
-// problem -- this package only supplies the mapping.
+// Where the two are known to differ (e.g. Button's real Figma component set
+// is named "Buttons", plural), figma/figmaComponentAliases.mjs supplies the
+// extra name(s) below, so the caller can still pass the raw Figma name
+// straight through with no normalization of its own.
 //
 // Returns Some((props, codeComponent)) for anything synced/verified, None
 // otherwise -- the caller supplies its own tag prefix/wrapper (e.g.
@@ -266,7 +269,8 @@ async function main() {
     }
   }
 
-  const registryResult = await writeRegistry(generated);
+  const aliases = existsSync(ALIASES_PATH) ? (await import(ALIASES_PATH)).default : {};
+  const registryResult = await writeRegistry(generated, aliases);
 
   for (const r of generated) console.log(`wrote src/Figma/${r.componentName}CodeConnect.res`);
   for (const f of removed) console.log(`removed stale src/Figma/${f} (no longer a ready map)`);

src/Figma/CodeConnectRegistry.res

@@ -7,15 +7,10 @@
 // IMPORTANT: figmaComponentName is whatever identifier blend-design-system's
 // own *.figma.tsx uses in its figma.connect(<ComponentName>, ...) call --
 // NOT necessarily the literal name shown in Figma's layers/Inspect panel.
-// These can differ: Button's real Figma component set is named "Buttons"
-// (plural, confirmed via Figma Desktop's Inspect panel), while blend's
-// figma.connect() call uses the React identifier "Button" (singular), so
-// this registry's "Button" key won't match a raw Figma layer name of
-// "Buttons" without the caller normalizing first (same idea as
-// juspay-portal's existing ^ComponentName \d+$ instance-suffix
-// normalization). Resolving the actual Figma component name from a live
-// node, and reconciling it against this registry's keys, is the caller's
-// problem -- this package only supplies the mapping.
+// Where the two are known to differ (e.g. Button's real Figma component set
+// is named "Buttons", plural), figma/figmaComponentAliases.mjs supplies the
+// extra name(s) below, so the caller can still pass the raw Figma name
+// straight through with no normalization of its own.
 //
 // Returns Some((props, codeComponent)) for anything synced/verified, None
 // otherwise -- the caller supplies its own tag prefix/wrapper (e.g.
@@ -27,7 +22,7 @@ let resolve = (figmaComponentName: string, props: CodeConnectUtils.figmaProps):
 )> =>
   switch figmaComponentName {
   | "AvatarGroup" => Some((AvatarGroupCodeConnect.toProps(props), "AvatarGroup"))
-  | "Button" => Some((ButtonCodeConnect.toProps(props), "Button"))
+  | "Button" | "Buttons" => Some((ButtonCodeConnect.toProps(props), "Button"))
   | "ButtonGroup" => Some((ButtonGroupCodeConnect.toProps(props), "ButtonGroup"))
   | "Charts" => Some((ChartsCodeConnect.toProps(props), "Charts"))
   | "DropdownInput" => Some((DropdownInputCodeConnect.toProps(props), "DropdownInput"))