@radicool/throughline 0.24.0 → 0.26.0

package/scripts/lib/figma-variables-read.figma.js

@@ -0,0 +1,39 @@
+// Figma plugin-API helpers for reading colour variables, shared by the Figma
+// checks reader and the screen reader. This file is NOT a Node module:
+// build-figma-checks.mjs inlines it into both generated scripts
+// (references/figma-checks.md, references/figma-adherence.md). It depends on
+// nothing else, so it carries its own mode-name fold. Async getters only
+// (references/figma-scripting.md). Untested in Node, like the readers.
+
+const foldModeName = (s) => String(s).toLowerCase().replace(/[^a-z0-9]/g, '');
+
+function colorHex(value) {
+  if (!value || typeof value !== 'object' || !('r' in value)) return null;
+  const byte = (x) => Math.round(x * 255).toString(16).padStart(2, '0');
+  const alpha = value.a === undefined ? 1 : value.a;
+  return `#${byte(value.r)}${byte(value.g)}${byte(value.b)}${alpha < 1 ? byte(alpha) : ''}`;
+}
+
+// The value of `variable` in the mode named `modeName` (after the fold), else
+// its collection's default mode, following aliases up to 10 hops.
+async function resolveColor(variable, modeName, hops) {
+  if (!variable || hops > 10) return null;
+  const collection = await figma.variables.getVariableCollectionByIdAsync(variable.variableCollectionId);
+  if (!collection) return null;
+  const mode = collection.modes.find((m) => foldModeName(m.name) === foldModeName(modeName));
+  const value = variable.valuesByMode[mode ? mode.modeId : collection.defaultModeId];
+  if (value && value.type === 'VARIABLE_ALIAS') {
+    return resolveColor(await figma.variables.getVariableByIdAsync(value.id), modeName, hops + 1);
+  }
+  return colorHex(value);
+}
+
+// { modes: { [modeName]: hex | null }, defaultMode } over the variable's own collection.
+async function variableColors(variable) {
+  const collection = await figma.variables.getVariableCollectionByIdAsync(variable.variableCollectionId);
+  if (!collection) return { modes: {}, defaultMode: undefined };
+  const modes = {};
+  for (const mode of collection.modes) modes[mode.name] = await resolveColor(variable, mode.name, 0);
+  const fallback = collection.modes.find((m) => m.modeId === collection.defaultModeId);
+  return { modes, defaultMode: fallback ? fallback.name : undefined };
+}

package/scripts/lib/fixtures/figma-adherence/clean.json

@@ -0,0 +1,90 @@
+{
+  "covers": "everything bound passes with no advisories",
+  "snapshot": {
+    "fileKey": "FILE",
+    "screens": [
+      {
+        "id": "0:1",
+        "name": "Screen"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "1:1",
+        "path": "Templates / Screen / Node",
+        "isRoot": false,
+        "inInstance": false,
+        "overridden": [],
+        "paints": [
+          {
+            "kind": "fill",
+            "hex": "#ffffff",
+            "bound": true,
+            "styled": false
+          },
+          {
+            "kind": "stroke",
+            "hex": "#111827",
+            "bound": false,
+            "styled": true
+          }
+        ],
+        "mixedPaints": false,
+        "gap": {
+          "value": 12,
+          "bound": true,
+          "renders": true
+        },
+        "padding": [
+          {
+            "side": "top",
+            "value": 16,
+            "bound": true
+          }
+        ],
+        "radius": [
+          {
+            "corner": "all",
+            "value": 8,
+            "bound": true
+          }
+        ],
+        "detached": null
+      }
+    ],
+    "tokens": {
+      "colours": {
+        "#ffffff": [
+          "color/bg/canvas"
+        ],
+        "#111827": [
+          "color/text/primary"
+        ]
+      },
+      "gap": {
+        "8": [
+          "spacing/2"
+        ],
+        "12": [
+          "spacing/3"
+        ],
+        "16": [
+          "spacing/4"
+        ]
+      },
+      "radius": {
+        "8": [
+          "radius/md"
+        ],
+        "32": [
+          "radius/xl"
+        ]
+      }
+    }
+  },
+  "expected": {
+    "pass": true,
+    "failures": [],
+    "advisories": 0
+  }
+}

package/scripts/lib/fixtures/figma-adherence/detached-library.json

@@ -0,0 +1,116 @@
+{
+  "covers": "01. Design System 2026-10-13: a frame detached from a library component, and one from a local component on another page; raw values inside a detached frame are not reported again",
+  "snapshot": {
+    "fileKey": "FILE",
+    "screens": [
+      {
+        "id": "0:1",
+        "name": "Screen"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "4:1",
+        "path": "Archtypes / hud-Jordan",
+        "isRoot": false,
+        "inInstance": false,
+        "overridden": [],
+        "paints": [],
+        "mixedPaints": false,
+        "gap": null,
+        "padding": [],
+        "radius": [],
+        "detached": {
+          "kind": "library",
+          "name": null,
+          "id": null,
+          "key": "4412e315f15a0af7a26382d2b05781f7974a30d9"
+        },
+        "underDetached": true
+      },
+      {
+        "id": "4:2",
+        "path": "Archtypes / hud-maria",
+        "isRoot": false,
+        "inInstance": false,
+        "overridden": [],
+        "paints": [],
+        "mixedPaints": false,
+        "gap": null,
+        "padding": [],
+        "radius": [],
+        "detached": {
+          "kind": "local",
+          "name": null,
+          "id": "9:9",
+          "key": null
+        },
+        "underDetached": true
+      },
+      {
+        "id": "4:3",
+        "path": "Archtypes / hud-Jordan / Card",
+        "isRoot": false,
+        "inInstance": false,
+        "overridden": [],
+        "paints": [
+          {
+            "kind": "fill",
+            "hex": "#ffffff",
+            "bound": false,
+            "styled": false
+          }
+        ],
+        "mixedPaints": false,
+        "gap": null,
+        "padding": [
+          {
+            "side": "top",
+            "value": 16,
+            "bound": false
+          }
+        ],
+        "radius": [],
+        "detached": null,
+        "underDetached": true
+      }
+    ],
+    "tokens": {
+      "colours": {
+        "#ffffff": [
+          "color/bg/canvas"
+        ],
+        "#111827": [
+          "color/text/primary"
+        ]
+      },
+      "gap": {
+        "8": [
+          "spacing/2"
+        ],
+        "12": [
+          "spacing/3"
+        ],
+        "16": [
+          "spacing/4"
+        ]
+      },
+      "radius": {
+        "8": [
+          "radius/md"
+        ],
+        "32": [
+          "radius/xl"
+        ]
+      }
+    }
+  },
+  "expected": {
+    "pass": false,
+    "failures": [
+      "detached-component",
+      "detached-component"
+    ],
+    "advisories": 0
+  }
+}

package/scripts/lib/fixtures/figma-adherence/ds01-gaps.json

@@ -0,0 +1,84 @@
+{
+  "covers": "01. Design System 2026-10-13: a rendering gap of 12 fails naming the token; a one-child gap of 8 is not checked",
+  "snapshot": {
+    "fileKey": "FILE",
+    "screens": [
+      {
+        "id": "0:1",
+        "name": "Screen"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "2:1",
+        "path": "Templates / hero / Frame 6",
+        "isRoot": false,
+        "inInstance": false,
+        "overridden": [],
+        "paints": [],
+        "mixedPaints": false,
+        "gap": {
+          "value": 12,
+          "bound": false,
+          "renders": true
+        },
+        "padding": [],
+        "radius": [],
+        "detached": null
+      },
+      {
+        "id": "2:2",
+        "path": "Templates / hero / container-left",
+        "isRoot": false,
+        "inInstance": false,
+        "overridden": [],
+        "paints": [],
+        "mixedPaints": false,
+        "gap": {
+          "value": 8,
+          "bound": false,
+          "renders": false
+        },
+        "padding": [],
+        "radius": [],
+        "detached": null
+      }
+    ],
+    "tokens": {
+      "colours": {
+        "#ffffff": [
+          "color/bg/canvas"
+        ],
+        "#111827": [
+          "color/text/primary"
+        ]
+      },
+      "gap": {
+        "8": [
+          "spacing/2"
+        ],
+        "12": [
+          "spacing/3"
+        ],
+        "16": [
+          "spacing/4"
+        ]
+      },
+      "radius": {
+        "8": [
+          "radius/md"
+        ],
+        "32": [
+          "radius/xl"
+        ]
+      }
+    }
+  },
+  "expected": {
+    "pass": false,
+    "failures": [
+      "raw-dimension"
+    ],
+    "advisories": 0
+  }
+}

package/scripts/lib/fixtures/figma-adherence/inert-all.json

@@ -0,0 +1,45 @@
+{
+  "covers": "a file with no colour or dimension variables fails both inert checks",
+  "tokens": {
+    "colours": {},
+    "gap": {},
+    "radius": {}
+  },
+  "snapshot": {
+    "fileKey": "FILE",
+    "screens": [
+      {
+        "id": "0:1",
+        "name": "Screen"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "1:1",
+        "path": "Templates / Screen / Node",
+        "isRoot": false,
+        "inInstance": false,
+        "overridden": [],
+        "paints": [],
+        "mixedPaints": false,
+        "gap": null,
+        "padding": [],
+        "radius": [],
+        "detached": null
+      }
+    ],
+    "tokens": {
+      "colours": {},
+      "gap": {},
+      "radius": {}
+    }
+  },
+  "expected": {
+    "pass": false,
+    "failures": [
+      "colour-rule-inert",
+      "dimension-rule-inert"
+    ],
+    "advisories": 0
+  }
+}

package/scripts/lib/fixtures/figma-adherence/mixed-text.json

@@ -0,0 +1,61 @@
+{
+  "covers": "a text node with mixed paints is an advisory, not a pass and not a crash",
+  "snapshot": {
+    "fileKey": "FILE",
+    "screens": [
+      {
+        "id": "0:1",
+        "name": "Screen"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "1:1",
+        "path": "Templates / Screen / Node",
+        "isRoot": false,
+        "inInstance": false,
+        "overridden": [],
+        "paints": [],
+        "mixedPaints": true,
+        "gap": null,
+        "padding": [],
+        "radius": [],
+        "detached": null
+      }
+    ],
+    "tokens": {
+      "colours": {
+        "#ffffff": [
+          "color/bg/canvas"
+        ],
+        "#111827": [
+          "color/text/primary"
+        ]
+      },
+      "gap": {
+        "8": [
+          "spacing/2"
+        ],
+        "12": [
+          "spacing/3"
+        ],
+        "16": [
+          "spacing/4"
+        ]
+      },
+      "radius": {
+        "8": [
+          "radius/md"
+        ],
+        "32": [
+          "radius/xl"
+        ]
+      }
+    }
+  },
+  "expected": {
+    "pass": true,
+    "failures": [],
+    "advisories": 1
+  }
+}

package/scripts/lib/fixtures/figma-adherence/nothing-scanned.json

@@ -0,0 +1,49 @@
+{
+  "covers": "no nodes read fails",
+  "snapshot": {
+    "fileKey": "FILE",
+    "screens": [
+      {
+        "id": "0:1",
+        "name": "Screen"
+      }
+    ],
+    "nodes": [],
+    "tokens": {
+      "colours": {
+        "#ffffff": [
+          "color/bg/canvas"
+        ],
+        "#111827": [
+          "color/text/primary"
+        ]
+      },
+      "gap": {
+        "8": [
+          "spacing/2"
+        ],
+        "12": [
+          "spacing/3"
+        ],
+        "16": [
+          "spacing/4"
+        ]
+      },
+      "radius": {
+        "8": [
+          "radius/md"
+        ],
+        "32": [
+          "radius/xl"
+        ]
+      }
+    }
+  },
+  "expected": {
+    "pass": false,
+    "failures": [
+      "nothing-scanned"
+    ],
+    "advisories": 0
+  }
+}

package/scripts/lib/fixtures/figma-adherence/off-scale-gap.json

@@ -0,0 +1,65 @@
+{
+  "covers": "Zygarden 2026-10-13: a 200 gap no token has is an advisory",
+  "snapshot": {
+    "fileKey": "FILE",
+    "screens": [
+      {
+        "id": "0:1",
+        "name": "Screen"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "1:1",
+        "path": "Templates / bg",
+        "isRoot": false,
+        "inInstance": false,
+        "overridden": [],
+        "paints": [],
+        "mixedPaints": false,
+        "gap": {
+          "value": 200,
+          "bound": false,
+          "renders": true
+        },
+        "padding": [],
+        "radius": [],
+        "detached": null
+      }
+    ],
+    "tokens": {
+      "colours": {
+        "#ffffff": [
+          "color/bg/canvas"
+        ],
+        "#111827": [
+          "color/text/primary"
+        ]
+      },
+      "gap": {
+        "8": [
+          "spacing/2"
+        ],
+        "12": [
+          "spacing/3"
+        ],
+        "16": [
+          "spacing/4"
+        ]
+      },
+      "radius": {
+        "8": [
+          "radius/md"
+        ],
+        "32": [
+          "radius/xl"
+        ]
+      }
+    }
+  },
+  "expected": {
+    "pass": true,
+    "failures": [],
+    "advisories": 1
+  }
+}

package/scripts/lib/fixtures/figma-adherence/override-raw.json

@@ -0,0 +1,72 @@
+{
+  "covers": "an overridden fill inside an instance, unbound and token-valued, fails",
+  "snapshot": {
+    "fileKey": "FILE",
+    "screens": [
+      {
+        "id": "0:1",
+        "name": "Screen"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "1:1",
+        "path": "Templates / Screen / Node",
+        "isRoot": false,
+        "inInstance": true,
+        "overridden": [
+          "fills"
+        ],
+        "paints": [
+          {
+            "kind": "fill",
+            "hex": "#111827",
+            "bound": false,
+            "styled": false
+          }
+        ],
+        "mixedPaints": false,
+        "gap": null,
+        "padding": [],
+        "radius": [],
+        "detached": null
+      }
+    ],
+    "tokens": {
+      "colours": {
+        "#ffffff": [
+          "color/bg/canvas"
+        ],
+        "#111827": [
+          "color/text/primary"
+        ]
+      },
+      "gap": {
+        "8": [
+          "spacing/2"
+        ],
+        "12": [
+          "spacing/3"
+        ],
+        "16": [
+          "spacing/4"
+        ]
+      },
+      "radius": {
+        "8": [
+          "radius/md"
+        ],
+        "32": [
+          "radius/xl"
+        ]
+      }
+    }
+  },
+  "expected": {
+    "pass": false,
+    "failures": [
+      "raw-colour"
+    ],
+    "advisories": 0
+  }
+}

package/scripts/lib/fixtures/figma-adherence/padding-raw.json

@@ -0,0 +1,74 @@
+{
+  "covers": "an unbound padding side a token has fails",
+  "snapshot": {
+    "fileKey": "FILE",
+    "screens": [
+      {
+        "id": "0:1",
+        "name": "Screen"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "1:1",
+        "path": "Templates / Screen / Node",
+        "isRoot": false,
+        "inInstance": false,
+        "overridden": [],
+        "paints": [],
+        "mixedPaints": false,
+        "gap": null,
+        "padding": [
+          {
+            "side": "left",
+            "value": 16,
+            "bound": false
+          },
+          {
+            "side": "top",
+            "value": 16,
+            "bound": true
+          }
+        ],
+        "radius": [],
+        "detached": null
+      }
+    ],
+    "tokens": {
+      "colours": {
+        "#ffffff": [
+          "color/bg/canvas"
+        ],
+        "#111827": [
+          "color/text/primary"
+        ]
+      },
+      "gap": {
+        "8": [
+          "spacing/2"
+        ],
+        "12": [
+          "spacing/3"
+        ],
+        "16": [
+          "spacing/4"
+        ]
+      },
+      "radius": {
+        "8": [
+          "radius/md"
+        ],
+        "32": [
+          "radius/xl"
+        ]
+      }
+    }
+  },
+  "expected": {
+    "pass": false,
+    "failures": [
+      "raw-dimension"
+    ],
+    "advisories": 0
+  }
+}