@scattered-light/loomiere 0.4.0 → 0.5.0

package/exporters/index.mjs

@@ -30,6 +30,10 @@ const wanted = (id, only) => only === 'all' || only.some((pick) => id === pick |
  */
 export function exportAll(catalog, roles, outDir, only = 'all', context = {}) {
   const theme = readTheme(catalog, roles);
+  // A brand with several looks: each look's own theme, the brand's own look first.
+  if (context.looks?.length > 1) {
+    theme.looks = context.looks.map(({ name, label, description, base, catalog: c, roles: r }) => ({ name, label, description, base, theme: base ? theme : readTheme(c, r) }));
+  }
   // tokens.css sits beside exports/; adapters that re-use its rules (Tailwind's pair and scope
   // utilities) read it from here.
   const tokensCss = path.join(outDir, '..', 'tokens.css');

package/figma/README.md

@@ -27,7 +27,7 @@ group in a hidden collection, and the published collection's modes point at the
 
 | Collection     | Modes                                                                                                     | Holds                                                                                                                                                                                                                                                                                                                                                                                                               |
 | -------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Brand (hidden) | Default                                                                                                   | Font families, and a complete group of the brand's colors per theme: `default/color/…`, then `deuteranopia/color/…` and the other color vision themes. Data colors are here by name (`color/data/violet`). A color a vision theme doesn't change points at default's.                                                                                                                                               |
+| Brand (hidden; published with looks) | Default, or one per look                                                                                  | Font families, and a complete group of the brand's colors per theme: `default/color/…`, then `deuteranopia/color/…` and the other color vision themes. Data colors are here by name (`color/data/violet`). A color a vision theme doesn't change points at default's.                                                                                                                                               |
 | Scale (hidden) | Default                                                                                                   | The raw steps: space, radius, stroke and icon size scales, and the font sizes as `desktop/`, `tablet/` and `mobile/font-size/…`, each `clamp()` read at that width (tablet at 768px).                                                                                                                                                                                                                               |
 | Size           | Desktop, Tablet, Mobile                                                                                   | The sizes designers pick: font sizes, and the named semantic and component sizes (control heights, gaps, padding), each pointing at a Scale step.                                                                                                                                                                                                                                                                   |
 | Theme          | Light, Dark, Light high contrast, Dark high contrast, Deuteranopia, Protanopia, Tritanopia, Achromatopsia | The themes, as `data-theme` in CSS. Each color vision theme is a light theme of its own with the brand's colors redesigned for that kind of color vision. Holds every semantic color designers pick, the data series slots (`data/1`…, each pointing at the named data color that theme puts there), and, with no scopes, the palette scopes and each brand pair's parts (`pair/<name>/bg`…) that Status points at. |
@@ -50,6 +50,21 @@ Effect styles hold what a variable can't: elevation/xs to elevation/2xl from the
 focus/ring (gap, ring and halo), and focus/field and focus/field-error for fields. Shadow colors that are
 Theme tokens stay bound, so the focus styles follow light, dark and the other themes.
 
+### Looks
+
+A brand with [looks](../tokens/README.md#looks) gets one Brand mode per look, the brand's own
+first (Mojave, Classic). Everything else stays as it is: a value in Scale, Size or Theme that
+differs between looks points at a Brand variable named `look/<collection>/<mode>/<name>`
+(`look/theme/light/scope/accent/solid`), which holds each look's value. Set the Brand mode on a
+frame to switch its look; Theme, Size, Status and Emphasis still switch on their own.
+
+With looks, Brand is published, so a file that uses the library can set the look too. Its
+variables still have no scopes, so they stay out of the color and number pickers.
+
+Limits: text styles and effect styles come from the brand's own look. A text style's size and
+family are variables, so they follow the look, but its line height and letter spacing are fixed
+numbers. Shadow colors that aren't Theme tokens are the brand look's.
+
 ### Plans
 
 Modes per collection depend on the Figma plan: Professional allows 10, Organization 20. The sync
@@ -126,10 +141,11 @@ has.
 
 ## Files
 
-| File                               | What it is                                                                                                                                              |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `../exporters/figma.mjs`           | Writes `figma.json` from the token catalog.                                                                                                             |
-| `engine.js`                        | The sync engine: plain JavaScript for Figma's plugin API, with no imports, so the plugin, the push scripts and Node all run the same text.              |
-| `../lib/figma.mjs`                 | `loomiere figma`: the push scripts, the four ways, `serve`.                                                                                             |
-| `plugin/`                          | The plugin. `code.js` is generated from `engine.js` and `plugin-main.js` by `npm run build -w @scattered-light/loomiere`.                               |
-| `../../../scripts/check-figma.mjs` | `npm run check:figma`: runs the engine against a stand-in for Figma's API in both layouts, whole and in parts, and checks a second run changes nothing. |
+| File                               | What it is                                                                                                                                                                        |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `../exporters/figma.mjs`           | Writes `figma.json` from the token catalog.                                                                                                                                       |
+| `engine.js`                        | The sync engine: plain JavaScript for Figma's plugin API, with no imports, so the plugin, the push scripts and Node all run the same text.                                        |
+| `../lib/figma.mjs`                 | `loomiere figma`: the push scripts, the four ways, `serve`.                                                                                                                       |
+| `library/`                         | The scripts that draw the library pages (foundations, components, docs, Cover) in a file, with a run order and checks against Mojave. See [library/README.md](library/README.md). |
+| `plugin/`                          | The plugin. `code.js` is generated from `engine.js` and `plugin-main.js` by `npm run build -w @scattered-light/loomiere`.                                                         |
+| `../../../scripts/check-figma.mjs` | `npm run check:figma`: runs the engine against a stand-in for Figma's API in both layouts, whole and in parts, and checks a second run changes nothing.                           |

package/figma/library/README.md

@@ -0,0 +1,92 @@
+# Figma library pages
+
+The scripts that draw the library's pages in a Figma file: the foundation pages (Palettes, Color,
+Type, Scale, Size, Elevation, Themes), every component set with its labels, each page's doc
+frame, and the Cover. They read the file's variables, text styles and effect styles by name, so
+the same scripts build the Mojave file or any copy synced with another brand.
+
+They used to live only in the Mojave file. Here they can rebuild a page in any copy, or the whole
+library in a new file, and a check run proves the result matches Mojave.
+
+## Before you start
+
+The file needs the theme first: run a Figma sync (`loomiere figma push`, or "sync Figma" in a
+chat; see [../README.md](../README.md)). The page scripts only draw. They never create variables or
+styles, and they stop with "No variable …" if one is missing.
+
+Scripts run through the Figma connector's `use_figma`, which takes up to 50,000 characters of
+code and has no network access. So the shared code (the kit) is stored in the file itself, and
+each page script loads it from there.
+
+## Build or patch a file
+
+```sh
+# A new file, or after a kit change: store the kit, then every page in order.
+node tools/runs.mjs --store
+# Only some pages, in run order. Each script rebuilds its page's sets and doc frame.
+node tools/runs.mjs --pages Fields,Themes
+```
+
+`runs.mjs` packs [run-order.json](run-order.json) into as few scripts as fit under the limit and
+writes them to `runs/` as `run-01.js`, `run-02.js`… Run them in the file in that order. Each
+prints what it built; a script that fails partway can be run again, since every script removes
+what it made last time before drawing.
+
+The order matters because pages use each other's components: Fields needs Button for some of its
+sets, Themes shows Field, Select, Checkbox and Switch, and the later pages use Button, Field and
+Toggle. When a page changes, rebuild it and then the pages after it that use its sets.
+
+### What a rebuild replaces
+
+A rebuild deletes a component set and draws it again. Instances inside the library pages are
+redrawn with it. Instances anywhere else in the file, such as screens in a project copy, still
+point at the deleted set and stop updating. So in a copy that already has designs:
+
+- Change colors, sizes, type and effects with a Figma sync. It updates variables and styles in
+  place, and every bound layer follows.
+- Add a new component by running its page's scripts. Sets that already exist are rebuilt in the
+  same place, so run only on files where nothing outside the library uses them yet, or rebuild
+  just the new set's script.
+
+## Check a run against Mojave
+
+```sh
+node tools/runs.mjs --check --pages Overlays      # draws on a "✱ check / Overlays" page
+node tools/run.mjs --units Overlays               # a script that returns the page's fingerprints
+node tools/compare.mjs Overlays '<fingerprints>'  # compares with check/mojave.json
+node tools/run.mjs --diff Overlays=set:Dialog,doc:Overlays/Dialog   # the layers that differ
+```
+
+A check run builds on pages named "✱ check / …" beside the real ones and never touches the real
+pages. Components it needs from pages that have no check page come from the real ones. Delete
+the check pages when done, and clear the prefix with `node tools/run.mjs --real` (a script that
+only resets it).
+
+Fingerprints are short hashes of what each set, wrapper and doc section looks like: sizes,
+layout, variables by name, text styles, instance targets. They never use node IDs, so two files
+built the same way match. [check/known-differences.md](check/known-differences.md) lists where
+Mojave and the scripts differ on purpose.
+
+## Files
+
+| File                                         | What it is                                                                                                          |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `kit/base.js`                                | Lookups for variables, styles and pages, and the small builders every script uses. Stored as `docHelpers`.          |
+| `kit/components.js`                          | base.js plus icons, focus rings, component helpers, the Components column and `labelSets`. Stored as `compHelpers`. |
+| `kit/docs.js`                                | base.js plus stages, captions, usage columns and spec tables for doc frames. Stored as `docKit`.                    |
+| `kit/fingerprint.js`                         | Fingerprints and layer diffs for checks. Stored as `fingerprint`.                                                   |
+| `pages/`                                     | One script per foundation page; a folder per component page, numbered in run order.                                 |
+| `run-order.json`                             | The order to run the page scripts in.                                                                               |
+| `tools/kit-script.mjs`                       | Writes the script that stores the kit (`--only docKit` for one part, `--hashes` to compare).                        |
+| `tools/run.mjs`                              | Bundles scripts into one `use_figma` script; `--check`, `--real`, `--store`, `--units`, `--diff`.                   |
+| `tools/runs.mjs`                             | Packs run-order.json into numbered scripts under the size limit.                                                    |
+| `tools/compare.mjs`, `tools/diff-snippet.js` | Compare fingerprints with Mojave, and show the layers that differ.                                                  |
+| `check/mojave.json`                          | Mojave's fingerprints, 23 October 2026.                                                                             |
+
+## Adding a component
+
+Write its script in the page's folder, after the existing ones: build the variants with the kit's
+`comp`, combine them, give the set a description, then `place(set)` so it joins the Components
+column. Add it to the page's labels script and doc script, and to `run-order.json`. Run it with
+`--check` first, look at it, then run it for real. Once it is in Mojave, refresh `check/mojave.json`
+with a `--units` run of that page.

package/figma/library/check/known-differences.md

@@ -0,0 +1,20 @@
+# Known differences from Mojave
+
+`check/mojave.json` holds the fingerprints of the Mojave file as it stood on 23 October 2026. A check
+run of every page matches it, except for the differences below. In each case the scripts are right
+and Mojave is out of date: either Mojave was built before a later change, or text was edited by
+hand in Mojave and the scripts now carry the edit.
+
+| Page    | Where                                         | Difference                                                                                                                  |
+| ------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Color   | Contrast tables                               | Mojave shows older ratios; the scripts compute them from the current variables when they run.                               |
+| Color   | Theme rows                                    | Mojave's rows follow the old variable order; the scripts follow the current order.                                          |
+| Size    | Opacity rows                                  | Mojave shows opacity as 0.5; the scripts show 50, which is how Figma reads a bound opacity.                                 |
+| Fields  | Picker rows 5 to 8, the Combobox "Avoid" line | Layer names. The text was edited in place in Mojave, so the layers kept their old names.                                    |
+| Buttons | Picker row 5                                  | Layer name, as above.                                                                                                       |
+| Popups  | Picker rows 7 to 9                            | Layer names, as above.                                                                                                      |
+| Cover   | Lead text                                     | Layer name, as above.                                                                                                       |
+| Cover   | Title block                                   | Mojave reports hug width while being 600 wide; the script fixes it at 600, since a hugging block would shrink to the title. |
+
+When a check shows a difference that is not on this list, either a script or Mojave changed. Run
+`node tools/run.mjs --diff Page=unit,unit` to see the layers that differ.

package/figma/library/check/mojave.json

@@ -0,0 +1,246 @@
+{
+ "file": "4vd4kRXowo3AjoQNWsDu0D",
+ "taken": "2026-10-23",
+ "pages": {
+  "Cover": {
+   "frame:Cover": "12ef885a"
+  },
+  "Palettes": {
+   "doc:Palettes(frame)": "770c0cb8",
+   "doc:Palettes/Header": "aef6c9ee",
+   "doc:Palettes/Neutral": "935b1685",
+   "doc:Palettes/Primary": "bb6c309c",
+   "doc:Palettes/Secondary": "3caecc37",
+   "doc:Palettes/Tertiary": "0ff1f3f0",
+   "doc:Palettes/Quaternary": "f256b3b6",
+   "doc:Palettes/Info": "e19b2086",
+   "doc:Palettes/Success": "906f40a1",
+   "doc:Palettes/Warning": "a2b3b587",
+   "doc:Palettes/Error": "e558e4ef",
+   "doc:Palettes/Data colors": "18c701f7"
+  },
+  "Color": {
+   "doc:Color(frame)": "bc97eff3",
+   "doc:Color/Header": "06674d9c",
+   "doc:Color/How the layers fit": "255539db",
+   "doc:Color/Surfaces": "0cddb652",
+   "doc:Color/Text": "96bca119",
+   "doc:Color/Borders": "89f1f42d",
+   "doc:Color/Fills": "fc7b43a6",
+   "doc:Color/Interactive": "9284003b",
+   "doc:Color/Status": "fa79dc92",
+   "doc:Color/Focus and overlay": "07a1d16c",
+   "doc:Color/Long-form content": "dc067f0a",
+   "doc:Color/Status and emphasis": "5ab44147"
+  },
+  "Type": {
+   "doc:Type(frame)": "50dfb9ed",
+   "doc:Type/Header": "f00b32a5",
+   "doc:Type/Title": "06b09c65",
+   "doc:Type/Body": "1d34862d",
+   "doc:Type/Label": "11175252",
+   "doc:Type/Trigger": "14d64d28",
+   "doc:Type/Selected": "c79e22e5",
+   "doc:Type/Link": "8ff20a84",
+   "doc:Type/Subtitle": "a0a22231",
+   "doc:Type/Eyebrow": "03c9c6ae",
+   "doc:Type/Code": "5d3c6d39"
+  },
+  "Scale": {
+   "doc:Scale(frame)": "14751dc4",
+   "doc:Scale/Header": "f303ef41",
+   "doc:Scale/Space": "efb36c2c",
+   "doc:Scale/Radius": "5342775b",
+   "doc:Scale/Stroke": "9477db2c",
+   "doc:Scale/Font size": "78890681"
+  },
+  "Size": {
+   "doc:Size(frame)": "3da2a99c",
+   "doc:Size/Header": "7de475f6",
+   "doc:Size/Space": "a549b294",
+   "doc:Size/Radius": "22610155",
+   "doc:Size/Stroke": "d68d19fa",
+   "doc:Size/Controls and icons": "460221cb",
+   "doc:Size/Spec reference": "7f6192bc"
+  },
+  "Elevation, focus and motion": {
+   "doc:Elevation, focus and motion(frame)": "f3ae9a72",
+   "doc:Elevation, focus and motion/Header": "5a542c9e",
+   "doc:Elevation, focus and motion/Elevation": "c20ef33d",
+   "doc:Elevation, focus and motion/Focus": "59275e2f",
+   "doc:Elevation, focus and motion/Motion": "5371fc6a",
+   "doc:Elevation, focus and motion/Jobs": "d02b4be0"
+  },
+  "Themes": {
+   "doc:Themes(frame)": "8afb7fff",
+   "doc:Themes/Header": "6c4eb058",
+   "doc:Themes/All eight themes": "8a55f844"
+  },
+  "Fields": {
+   "set:Field": "f7cb48fb",
+   "set:Input": "6c2b0d54",
+   "set:Select": "442baeee",
+   "set:Textarea": "92f7f774",
+   "set:Checkbox": "2599731a",
+   "set:Radio": "91b6e532",
+   "set:Switch": "19bb0959",
+   "set:Combobox field": "01c1d61f",
+   "set:Autocomplete": "a81a3346",
+   "set:Number field": "58d13ece",
+   "set:OTP field": "f6a1224f",
+   "set:Checkbox group": "f5f67eac",
+   "set:Fieldset": "70450478",
+   "set:Form": "012115e1",
+   "frame:Components(shell)": "a43d23d9",
+   "doc:Fields(frame)": "1f58d1ef",
+   "doc:Fields/Header": "ac90f480",
+   "doc:Fields/Choosing a control": "60930777",
+   "doc:Fields/Field": "52eb7ea8",
+   "doc:Fields/Input, Select and Textarea": "667585cd",
+   "doc:Fields/Checkbox and Radio": "98e44af9",
+   "doc:Fields/Switch": "9f6d0241",
+   "doc:Fields/Combobox and Autocomplete": "39ad22a9",
+   "doc:Fields/Number field and OTP field": "3d859762",
+   "doc:Fields/Checkbox group": "2f95ef55",
+   "doc:Fields/Fieldset and Form": "ee563701",
+   "wrap:Field": "760b8799",
+   "wrap:Input": "d5883aac",
+   "wrap:Select": "94429931",
+   "wrap:Textarea": "88452dd3",
+   "wrap:Checkbox": "d0ade3f2",
+   "wrap:Radio": "97c80ea7",
+   "wrap:Switch": "740522a5",
+   "wrap:Combobox field": "46e241db",
+   "wrap:Autocomplete": "ed53691e",
+   "wrap:Number field": "738d8ca7",
+   "wrap:OTP field": "8476481b",
+   "wrap:Checkbox group": "04546bc2",
+   "wrap:Fieldset": "049ea0b8",
+   "wrap:Form": "80971363"
+  },
+  "Buttons": {
+   "set:Button": "59742be5",
+   "set:Toggle": "f85382f0",
+   "frame:Components(shell)": "b607a157",
+   "doc:Buttons(frame)": "fb3c0173",
+   "doc:Buttons/Header": "33e88cd7",
+   "doc:Buttons/Choosing a button": "10202b27",
+   "doc:Buttons/Emphasis and status": "ec54ae73",
+   "doc:Buttons/Sizes and icons": "75bcfc1c",
+   "doc:Buttons/Icon only": "05a78b7a",
+   "doc:Buttons/Toggle": "1b4b097e",
+   "wrap:Button": "6b3cb817",
+   "wrap:Toggle": "1c3b06ef"
+  },
+  "Popups": {
+   "set:Menu item": "f7b7f316",
+   "set:List item": "e0831f16",
+   "set:Popup part": "c5922528",
+   "set:Menu": "6f370851",
+   "set:List popup": "20c43337",
+   "set:Popover": "09663bde",
+   "set:Tooltip": "a649c419",
+   "set:Menubar trigger": "3b163892",
+   "set:Menubar": "b48c1f59",
+   "set:Context menu": "6036f0e7",
+   "set:Preview card": "c3aa3f00",
+   "frame:Components(shell)": "e98d9c96",
+   "doc:Popups(frame)": "63b5c8ea",
+   "doc:Popups/Header": "f33b648c",
+   "doc:Popups/Choosing a popup": "b5405324",
+   "doc:Popups/Menu": "03945f79",
+   "doc:Popups/Select and Combobox lists": "dd7345e6",
+   "doc:Popups/Popover": "deedd40c",
+   "doc:Popups/Tooltip": "3b34f8c2",
+   "doc:Popups/Context menu and Menubar": "88aa53f4",
+   "doc:Popups/Preview card": "d7b5638d",
+   "wrap:Menu item": "d5656be8",
+   "wrap:List item": "d6e17ed3",
+   "wrap:Popup part": "bfa16f2c",
+   "wrap:Menu": "4e21aec7",
+   "wrap:List popup": "df9d7af3",
+   "wrap:Popover": "6bcad5ee",
+   "wrap:Tooltip": "1871ff95",
+   "wrap:Menubar trigger": "c6bd01e6",
+   "wrap:Menubar": "38c11276",
+   "wrap:Context menu": "6aed485d",
+   "wrap:Preview card": "87d2bd4a"
+  },
+  "Overlays": {
+   "set:Dialog": "0561ff0b",
+   "set:Drawer": "5d4508a8",
+   "set:Toast": "f7e3afc8",
+   "frame:Components(shell)": "5ba0aa18",
+   "doc:Overlays(frame)": "52a37527",
+   "doc:Overlays/Header": "9779ec4e",
+   "doc:Overlays/Choosing an overlay": "953a3511",
+   "doc:Overlays/Dialog": "7c1d85f6",
+   "doc:Overlays/Drawer": "58eb79fb",
+   "doc:Overlays/Toast": "430c4eee",
+   "wrap:Dialog": "39d7f8c9",
+   "wrap:Drawer": "a7547195",
+   "wrap:Toast": "0dbfb765"
+  },
+  "Disclosure and navigation": {
+   "set:Tab": "9956f55e",
+   "set:Tab list": "65ecc9ee",
+   "set:Accordion item": "4bc88874",
+   "set:Accordion": "08a20c6c",
+   "set:Nav trigger": "6dfd79f5",
+   "set:Nav link": "95643ccc",
+   "set:Navigation menu": "5fe72c8b",
+   "set:Toolbar": "20cbc081",
+   "set:Toggle group": "7f7d2f59",
+   "set:Collapsible": "470bec8d",
+   "frame:Components(shell)": "b3fd0dbc",
+   "doc:Disclosure and navigation(frame)": "9a5954ea",
+   "doc:Disclosure and navigation/Header": "9b37279e",
+   "doc:Disclosure and navigation/Choosing": "466ca5a9",
+   "doc:Disclosure and navigation/Tabs": "5e99defe",
+   "doc:Disclosure and navigation/Accordion": "255fff5e",
+   "doc:Disclosure and navigation/Navigation menu": "26b02c57",
+   "doc:Disclosure and navigation/Toolbar and Toggle group": "6c530db2",
+   "doc:Disclosure and navigation/Collapsible": "b4718c92",
+   "wrap:Tab": "3882aa7d",
+   "wrap:Tab list": "25caa0a9",
+   "wrap:Accordion item": "2a40ca7f",
+   "wrap:Accordion": "13924902",
+   "wrap:Nav trigger": "d34f44b0",
+   "wrap:Nav link": "8270ab86",
+   "wrap:Navigation menu": "943b347c",
+   "wrap:Toolbar": "def74e8f",
+   "wrap:Toggle group": "0a9794a6",
+   "wrap:Collapsible": "5b849605"
+  },
+  "Display": {
+   "set:Avatar": "ecb75184",
+   "set:Avatar group": "4b3380bf",
+   "set:Meter": "91905363",
+   "set:Progress": "2bf6bde2",
+   "set:Slider": "d0a9f876",
+   "set:Table row": "65b9d02d",
+   "set:Table": "504ce16f",
+   "set:Separator": "4fc10c4f",
+   "set:Scroll area": "d975ef8a",
+   "frame:Components(shell)": "2d92208b",
+   "doc:Display(frame)": "8e3f9ff8",
+   "doc:Display/Header": "ac51b33b",
+   "doc:Display/Choosing": "9c898af9",
+   "doc:Display/Avatar": "e22c9ae4",
+   "doc:Display/Meter and Progress": "1ba30ce0",
+   "doc:Display/Slider": "41be582c",
+   "doc:Display/Table": "a0cb6855",
+   "doc:Display/Separator": "4ca97dbe",
+   "doc:Display/Scroll area": "64eeb8b1",
+   "wrap:Avatar": "41a8b826",
+   "wrap:Avatar group": "f4b9cf55",
+   "wrap:Meter": "81dd7d37",
+   "wrap:Progress": "a1e0c526",
+   "wrap:Slider": "9e3cc9bb",
+   "wrap:Table row": "53077168",
+   "wrap:Table": "c3b9a6c7",
+   "wrap:Separator": "4187560c",
+   "wrap:Scroll area": "d9c44942"
+  }
+ }
+}

package/figma/library/kit/base.js

@@ -0,0 +1,89 @@
+// The library kit's base: lookups by name for variables, text styles and pages, and the small
+// builders every page script uses (auto layout, text, fills bound to variables). Stored in the
+// file as shared plugin data ('loomiere', 'docHelpers'); scripts load it with
+//   var L = await new AsyncFunction('figma', figma.root.getSharedPluginData('loomiere', 'docHelpers'))(figma);
+// Pages are found by name. While a check runs, ('loomiere', 'pagePrefix') holds a prefix, so a
+// script builds "<prefix>Buttons" instead of touching the real Buttons page.
+var cols = await figma.variables.getLocalVariableCollectionsAsync(), allVars = await figma.variables.getLocalVariablesAsync();
+var CN = {}, COL = {}, V = {}, TS = {};
+cols.forEach(function (c) { CN[c.id] = c; COL[c.name] = c; });
+allVars.forEach(function (x) { V[CN[x.variableCollectionId].name + ':' + x.name] = x; });
+(await figma.getLocalTextStylesAsync()).forEach(function (s) { TS[s.name] = s; });
+// Every font the text styles use, so any brand's fonts are ready before text is made.
+var FONTS = {};
+Object.keys(TS).forEach(function (k) { var f = TS[k].fontName; FONTS[f.family + '/' + f.style] = f; });
+for (var fk in FONTS) await figma.loadFontAsync(FONTS[fk]);
+var PREFIX = figma.root.getSharedPluginData('loomiere', 'pagePrefix') || '';
+// The library's pages, in file order.
+var PAGES = ['Cover', 'Palettes', 'Color', 'Type', 'Scale', 'Size', 'Elevation, focus and motion', 'Themes', 'Fields', 'Buttons', 'Popups', 'Overlays', 'Disclosure and navigation', 'Display'];
+function v(k) { if (!V[k]) throw new Error('No variable ' + k); return V[k]; }
+function paint(k) { return figma.variables.setBoundVariableForPaint({ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', v(k)); }
+function fill(n, k) { n.fills = k ? [paint(k)] : []; return n; }
+function stroke(n, k, w, align) { n.strokes = [paint(k)]; n.strokeAlign = align || 'INSIDE'; if (typeof w === 'string') n.setBoundVariable('strokeWeight', v(w)); else n.strokeWeight = w || 1; return n; }
+function bind(n, fields, k) { (Array.isArray(fields) ? fields : [fields]).forEach(function (f) { n.setBoundVariable(f, v(k)); }); return n; }
+function radius(n, k) { return bind(n, ['topLeftRadius', 'topRightRadius', 'bottomLeftRadius', 'bottomRightRadius'], k); }
+function pad(n, block, inline) { if (block) bind(n, ['paddingTop', 'paddingBottom'], block); if (inline) bind(n, ['paddingLeft', 'paddingRight'], inline); return n; }
+function AL(dir, props) { var f = figma.createAutoLayout(dir || 'HORIZONTAL'); f.fills = []; f.clipsContent = false; if (props) f.set(props); return f; }
+function add(parent, kids) { kids.forEach(function (k) { if (k) parent.appendChild(k); }); return parent; }
+async function T(str, style, colorKey, w, name) {
+  var t = figma.createText();
+  if (!TS[style]) throw new Error('No text style ' + style);
+  await t.setTextStyleIdAsync(TS[style].id);
+  t.characters = str;
+  fill(t, colorKey || 'Theme:text/primary');
+  if (w) { t.resize(w, t.height); t.textAutoResize = 'HEIGHT'; }
+  t.name = name || str.slice(0, 40);
+  return t;
+}
+function unescape(s) { return (s || '').replace(/&(quot|#39|lt|gt|amp);/g, function (m, e) { return { quot: '"', '#39': "'", lt: '<', gt: '>', amp: '&' }[e]; }); }
+function mode(n, colName, modeName) { var c = COL[colName]; n.setExplicitVariableModeForCollection(c, c.modes.filter(function (m) { return m.name === modeName; })[0].modeId); return n; }
+// A library page by its name (with the check prefix while a check runs), or null.
+function findPage(name) { return figma.root.children.filter(function (x) { return x.name === PREFIX + name; })[0] || null; }
+// Switch to a library page, making it in its place in PAGES if the file doesn't have it.
+async function page(name) {
+  var p = findPage(name);
+  if (!p) {
+    p = figma.createPage(); p.name = PREFIX + name;
+    var at = PAGES.indexOf(name), next = null;
+    for (var i = at + 1; at !== -1 && i < PAGES.length && !next; i++) next = findPage(PAGES[i]);
+    if (next) figma.root.insertChild(figma.root.children.indexOf(next), p);
+  }
+  await figma.setCurrentPageAsync(p);
+  return p;
+}
+// A component set by name on another library page (loads that page).
+async function setOn(pageName, setName) {
+  // A check run falls back to the real page for sets it hasn't rebuilt yet.
+  var p = findPage(pageName) || (PREFIX && figma.root.children.filter(function (x) { return x.name === pageName; })[0]);
+  if (!p) throw new Error('No page ' + pageName);
+  await p.loadAsync();
+  var s = p.findAllWithCriteria({ types: ['COMPONENT_SET', 'COMPONENT'] }).filter(function (n) { return n.name === setName && (n.type === 'COMPONENT_SET' || n.parent.type !== 'COMPONENT_SET'); })[0];
+  if (!s) throw new Error('No component ' + setName + ' on ' + pageName);
+  return s;
+}
+async function docFrame(name, eyebrow, title, lead) {
+  var old = figma.currentPage.children.filter(function (x) { return x.name === name; });
+  old.forEach(function (x) { x.remove(); });
+  var f = AL('VERTICAL', { name: name, itemSpacing: 72, paddingTop: 96, paddingBottom: 120, paddingLeft: 96, paddingRight: 96 });
+  fill(f, 'Theme:surface/canvas');
+  f.resize(1440, 100); f.counterAxisSizingMode = 'FIXED'; f.primaryAxisSizingMode = 'AUTO';
+  var head = AL('VERTICAL', { name: 'Header', itemSpacing: 16 });
+  add(head, [await T(eyebrow, 'eyebrow-condense', 'Theme:text/accent'), await T(title, 'title-maximize'), await T(lead, 'body-magnify', 'Theme:text/secondary', 820)]);
+  add(f, [head]);
+  return f;
+}
+async function section(parent, title, intro) {
+  var s = AL('VERTICAL', { name: title, itemSpacing: 24 });
+  add(parent, [s]); s.layoutSizingHorizontal = 'FILL';
+  var h = AL('VERTICAL', { name: 'Section header', itemSpacing: 8 });
+  add(h, [await T(title, 'title-amplify'), intro ? await T(intro, 'body-base', 'Theme:text/secondary', 820) : null]);
+  add(s, [h]);
+  return s;
+}
+function hrow(parent) { var r = AL('HORIZONTAL', { itemSpacing: 24, counterAxisAlignItems: 'CENTER', paddingTop: 12, paddingBottom: 12 }); add(parent, [r]); r.layoutSizingHorizontal = 'FILL'; return r; }
+function divider(n) { n.strokes = [paint('Theme:border/subtle')]; n.strokeTopWeight = 0; n.strokeLeftWeight = 0; n.strokeRightWeight = 0; n.strokeBottomWeight = 1; return n; }
+function lum(c) { var f = function (x) { return x <= 0.03928 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4); }; return 0.2126 * f(c.r) + 0.7152 * f(c.g) + 0.0722 * f(c.b); }
+function ratio(a, b) { var x = lum(a), y = lum(b); return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05); }
+function resolved(k, node) { var r = v(k).resolveForConsumer(node); return r.value; }
+function hex(c) { var p = function (x) { return ('0' + Math.round(x * 255).toString(16)).slice(-2); }; return '#' + p(c.r) + p(c.g) + p(c.b); }
+return { V: V, COL: COL, TS: TS, PAGES: PAGES, PREFIX: PREFIX, v: v, paint: paint, fill: fill, stroke: stroke, bind: bind, radius: radius, pad: pad, AL: AL, add: add, T: T, unescape: unescape, mode: mode, findPage: findPage, page: page, setOn: setOn, docFrame: docFrame, section: section, hrow: hrow, divider: divider, lum: lum, ratio: ratio, resolved: resolved, hex: hex };

package/figma/library/kit/components.js

@@ -0,0 +1,95 @@
+// The kit for component scripts: everything in base.js, plus icons, focus rings, component and
+// variant helpers, and the page's Components column. Stored as ('loomiere', 'compHelpers').
+var L = await new (Object.getPrototypeOf(async function () {}).constructor)('figma', figma.root.getSharedPluginData('loomiere', 'docHelpers'))(figma);
+var V = L.V, COL = L.COL, TS = L.TS, v = L.v, paint = L.paint, fill = L.fill, stroke = L.stroke, bind = L.bind, radius = L.radius, pad = L.pad, AL = L.AL, add = L.add, T = L.T, mode = L.mode, page = L.page;
+function shadow(color, spread, opts) {
+  var e = { type: 'DROP_SHADOW', color: { r: 0, g: 0, b: 0, a: 1 }, offset: { x: 0, y: (opts && opts.y) || 0 }, radius: (opts && opts.blur) || 0, spread: spread, visible: true, blendMode: 'NORMAL', showShadowBehindNode: false };
+  return color ? figma.variables.setBoundVariableForEffect(e, 'color', v(color)) : Object.assign(e, { color: opts.rgba });
+}
+function focusRing() { return [shadow('Theme:surface/canvas', 2), shadow('Theme:focus/ring', 4), shadow('Theme:interactive/tint-hover', 6)]; }
+function icon(name, d, size, colorKey, weight) {
+  var f = figma.createFrame(); f.name = name; f.fills = []; f.resize(16, 16); f.clipsContent = false;
+  var vec = figma.createVector(); vec.vectorPaths = [{ windingRule: 'NONZERO', data: d }]; vec.fills = [];
+  vec.strokes = [paint(colorKey)]; vec.strokeWeight = weight || 1.5; vec.strokeCap = 'ROUND'; vec.strokeJoin = 'ROUND';
+  var xs = [], ys = []; d.replace(/(-?[\d.]+) (-?[\d.]+)/g, function (m, x, y) { xs.push(+x); ys.push(+y); });
+  f.appendChild(vec); vec.x = Math.min.apply(null, xs); vec.y = Math.min.apply(null, ys);
+  if (size !== 16) f.rescale(size / 16);
+  return f;
+}
+function comp(name, dir) { var c = figma.createComponent(); c.name = name; c.layoutMode = dir || 'HORIZONTAL'; c.primaryAxisSizingMode = 'AUTO'; c.counterAxisSizingMode = 'AUTO'; c.fills = []; return c; }
+function arrange(set, width) {
+  set.layoutMode = 'HORIZONTAL'; set.layoutWrap = 'WRAP'; set.itemSpacing = 24; set.counterAxisSpacing = 24;
+  set.paddingTop = set.paddingBottom = set.paddingLeft = set.paddingRight = 32;
+  set.primaryAxisSizingMode = 'FIXED'; set.counterAxisSizingMode = 'AUTO'; set.resize(width, set.height);
+  fill(set, 'Theme:surface/canvas'); set.strokes = [{ type: 'SOLID', color: { r: 0.592, g: 0.278, b: 1 } }]; set.dashPattern = [6, 4]; set.strokeWeight = 1; set.cornerRadius = 8;
+}
+function textProp(set, label, def, layerName) {
+  var key = set.addComponentProperty(label, 'TEXT', def);
+  set.findAllWithCriteria({ types: ['TEXT'] }).forEach(function (t) { if (t.name === layerName) t.componentPropertyReferences = Object.assign({}, t.componentPropertyReferences, { characters: key }); });
+  return key;
+}
+function boolProp(set, label, def, layerName) {
+  var key = set.addComponentProperty(label, 'BOOLEAN', def);
+  set.findAll(function (n) { return n.name === layerName; }).forEach(function (n) { n.componentPropertyReferences = Object.assign({}, n.componentPropertyReferences, { visible: key }); });
+  return key;
+}
+// Where a rebuilt set goes back: removeOld notes the slot of the set (or its labelled wrapper) it
+// removes, so place puts the new one in the same spot instead of at the end.
+var slot = null;
+function place(set) {
+  var col = figma.currentPage.children.filter(function (n) { return n.name === 'Components'; })[0];
+  if (!col) { col = AL('VERTICAL', { name: 'Components', itemSpacing: 80 }); col.x = 1600; col.y = 400; }
+  if (slot && slot.name === set.name && slot.index <= col.children.length) col.insertChild(slot.index, set); else col.appendChild(set);
+  slot = null;
+  return col;
+}
+function isWrap(n) { return n.type === 'FRAME' && n.getSharedPluginData('loomiere', 'wrap') === '1'; }
+function removeOld(name) {
+  figma.currentPage.findAll(function (n) { return n.name === name && (n.type === 'COMPONENT_SET' || isWrap(n)); }).forEach(function (n) {
+    if (n.removed) return;
+    if (n.parent && n.parent.name === 'Components') slot = { name: name, index: n.parent.children.indexOf(n) };
+    n.remove();
+  });
+}
+// A header and side labels for each bare set in the page's Components column: the set's name and
+// a line from desc (or its description), its column values above and row values to the left.
+// Sets already wrapped keep their labels; run it last on a page, after every set is built.
+async function labelSets(desc) {
+  desc = desc || {};
+  var comp = figma.currentPage.children.filter(function (n) { return n.name === 'Components'; })[0];
+  function bucket(vals, tol) { var out = []; vals.sort(function (a, b) { return a - b; }).forEach(function (v) { if (!out.length || v - out[out.length - 1][0] > tol) out.push([v]); else out[out.length - 1].push(v); }); return out.map(function (b) { return b[0]; }); }
+  function common(nodes) { var keys = Object.keys(nodes[0].variantProperties); return keys.filter(function (k) { return nodes.every(function (n) { return n.variantProperties[k] === nodes[0].variantProperties[k]; }); }).map(function (k) { return nodes[0].variantProperties[k]; }); }
+  var sets = comp.children.filter(function (c) { return c.type === 'COMPONENT_SET'; });
+  comp.itemSpacing = 120;
+  var LW = 120;
+  for (var i = 0; i < sets.length; i++) {
+    var s = sets[i], kids = s.children;
+    var w = AL('VERTICAL', { name: s.name, itemSpacing: 16 }); w.setSharedPluginData('loomiere', 'wrap', '1');
+    comp.insertChild(comp.children.indexOf(s), w);
+    var head = AL('VERTICAL', { name: 'Header', itemSpacing: 4 });
+    add(head, [await T(s.name, 'title-amplify'), await T(desc[s.name] || s.description || '', 'body-base', 'Theme:text/secondary', 720)]);
+    add(w, [head]);
+    var xs = bucket(kids.map(function (k) { return Math.round(k.x); }), 8), ys = bucket(kids.map(function (k) { return Math.round(k.y); }), 12);
+    var top = AL('HORIZONTAL', { name: 'Column labels row' });
+    var spacer = figma.createFrame(); spacer.name = 'Corner'; spacer.fills = []; spacer.resize(LW, 20);
+    var cl = figma.createFrame(); cl.name = 'Column labels'; cl.fills = []; cl.clipsContent = false; cl.resize(s.width, 20);
+    add(top, [spacer, cl]); add(w, [top]);
+    if (xs.length > 1) for (var c = 0; c < xs.length; c++) {
+      var col = kids.filter(function (k) { return Math.abs(Math.round(k.x) - xs[c]) <= 8; });
+      var t = await T(common(col).join(' · ').toUpperCase(), 'eyebrow-condense', 'Theme:text/tertiary'); cl.appendChild(t); t.x = xs[c]; t.y = 0;
+    }
+    var body = AL('HORIZONTAL', { name: 'Body' });
+    var rl = figma.createFrame(); rl.name = 'Row labels'; rl.fills = []; rl.clipsContent = false; rl.resize(LW, s.height);
+    add(body, [rl]); body.appendChild(s); add(w, [body]);
+    if (ys.length > 1) for (var r = 0; r < ys.length; r++) {
+      var row = kids.filter(function (k) { return Math.abs(Math.round(k.y) - ys[r]) <= 12; });
+      var mid = row.reduce(function (a, k) { return a + k.y + k.height / 2; }, 0) / row.length;
+      var t2 = await T(common(row).join(' · '), 'subtitle-condense', 'Theme:text/secondary', LW - 16); rl.appendChild(t2); t2.x = 0; t2.y = Math.round(mid - t2.height / 2);
+    }
+  }
+  comp.clipsContent = false;
+  comp.findAll(function (n) { return n.type === 'FRAME' && (isWrap(n) || ['Header', 'Column labels row', 'Body', 'Corner'].indexOf(n.name) !== -1); }).forEach(function (n) { n.clipsContent = false; });
+  return sets.map(function (s) { return s.name; });
+}
+
+return Object.assign({}, L, { shadow: shadow, focusRing: focusRing, icon: icon, comp: comp, arrange: arrange, textProp: textProp, boolProp: boolProp, place: place, removeOld: removeOld, labelSets: labelSets });