@scattered-light/loomiere 0.5.1 → 0.5.3

package/build/build-tokens.mjs

@@ -285,6 +285,34 @@ const inLook = (selectors, name) =>
     .map((s) => `${s.trim()}[data-look='${name}']`)
     .join(', ');
 
+/** Pair class name → Map of variable → value, read from pairBlocks' text. */
+const pairDeclarations = (text) =>
+  new Map([...(text ?? '').matchAll(/^\.[\w-]+-pair-([\w-]+) \{\n([\s\S]*?)\n\}/gm)].map(([, name, body]) => [name, declarationsIn(body)]));
+
+/**
+ * What a look's pair classes need beyond the brand's. The pairs and their re-pointed parts are
+ * the brand's, but a look's `tokens` can change the tokens that lead to them: a token the look
+ * points elsewhere (or newly at a re-pointed one) gets the look's value inside each pair, under
+ * [data-look='<name>'] .<prefix>-pair-<pair>, which outranks the brand's pair class.
+ */
+function lookPairBlocks(name, parts, base) {
+  const own = pairDeclarations(parts.rules.pairs);
+  const brand = pairDeclarations(base.rules.pairs);
+  const names = (m) => [...m.keys()].sort().join(',');
+  if (names(own) !== names(brand)) throw new Error(`Look "${name}" changes the pairs rules, not only values. A look can change colors, fonts and sizes, but it has to keep the brand's palettes, pairs, statuses and emphasis levels.`);
+  const blocks = [];
+  for (const [pair, decls] of brand) {
+    const mine = own.get(pair);
+    const lines = [];
+    for (const [v, value] of mine) if (decls.get(v) !== value) lines.push(`${v}: ${value};`);
+    // No longer leads to a re-pointed token in this look: restate the look's own value so the
+    // brand's declaration in the pair class doesn't win.
+    for (const v of decls.keys()) if (!mine.has(v) && parts.root[v] !== undefined) lines.push(`${v}: ${parts.root[v]};`);
+    if (lines.length) blocks.push(`[data-look='${name}'] .${prefix}-pair-${pair} {\n${indent(lines.join('\n'), 2)}\n}`);
+  }
+  return blocks.join('\n\n');
+}
+
 /** [rootBlocks, modeBlocks] for every look against the brand's own parts. */
 function lookBlocks(dictionary, base) {
   const roots = [];
@@ -293,8 +321,12 @@ function lookBlocks(dictionary, base) {
     for (const [rule, text] of Object.entries(parts.rules)) {
       // Color vision blocks list the data colors by name, so a look with its own names has its own.
       if (rule === 'vision') continue;
+      // A look's `tokens` can change what leads to a re-pointed token; lookPairBlocks restates those.
+      if (rule === 'pairs') continue;
       if (text !== base.rules[rule]) throw new Error(`Look "${name}" changes the ${rule} rules, not only values. A look can change colors, fonts and sizes, but it has to keep the brand's palettes, pairs, statuses and emphasis levels.`);
     }
+    const pairRules = lookPairBlocks(name, parts, base);
+    if (pairRules) modeRules.push(pairRules);
     const changed = Object.entries(parts.root).filter(([v, value]) => base.root[v] !== value);
     if (changed.length) roots.push(`/* Look: ${label} (data-look='${name}'). */\n[data-look='${name}'] {\n${indent(changed.map(([v, value]) => `${v}: ${value};`).join('\n'), 2)}\n}`);
     if (parts.rules.vision !== base.rules.vision) {

package/figma/engine.js

@@ -345,6 +345,25 @@ async function loomiereMigrate(dryRun) {
   return renamed;
 }
 
+async function loomiereLoadFonts(data) {
+  var families = {};
+  (data.textStyles || []).forEach(function (t) {
+    if (t.family) families[t.family] = true;
+  });
+  var want = [];
+  (await figma.getLocalTextStylesAsync()).forEach(function (s) {
+    want.push(s.fontName);
+  });
+  (await figma.listAvailableFontsAsync()).forEach(function (f) {
+    if (families[f.fontName.family]) want.push(f.fontName);
+  });
+  for (var i = 0; i < want.length; i++) {
+    try {
+      await figma.loadFontAsync(want[i]);
+    } catch (e) {}
+  }
+}
+
 async function loomiereSync(data, options) {
   options = options || {};
   if (!data || data.format !== "loomiere-figma")
@@ -353,6 +372,9 @@ async function loomiereSync(data, options) {
     );
   var dryRun = !!options.dryRun;
   var warnings = [];
+  // Text styles bind fontFamily to a variable, so changing that variable needs the
+  // new family loaded in every style the file's text styles use, and the old ones too.
+  if (!dryRun) await loomiereLoadFonts(data);
   var report = {
     dryRun: dryRun,
     brand: data.brand,

package/figma/library/README.md

@@ -1,8 +1,8 @@
 # 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
+Type, Scale, Size, Elevation, Themes), every component set with its labels, the mockup pages
+(Placeholders and Annotations), 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

package/figma/library/check/mojave.json

@@ -3,7 +3,7 @@
  "taken": "2026-10-23",
  "pages": {
   "Cover": {
-   "frame:Cover": "12ef885a"
+   "frame:Cover": "cec8276d"
   },
   "Palettes": {
    "doc:Palettes(frame)": "770c0cb8",
@@ -241,6 +241,46 @@
    "wrap:Table": "c3b9a6c7",
    "wrap:Separator": "4187560c",
    "wrap:Scroll area": "d9c44942"
+  },
+  "Placeholders": {
+   "set:Image": "6b5d6656",
+   "set:Logo": "47c823c8",
+   "set:Chart": "28776d88",
+   "set:Map": "4f92f366",
+   "set:Video": "a65cf8d7",
+   "set:Icon slot": "b77e9819",
+   "frame:Components(shell)": "32cad7bf",
+   "wrap:Image": "56eca3f2",
+   "wrap:Logo": "3e10c93a",
+   "wrap:Chart": "c3dc3c8d",
+   "wrap:Map": "f5824235",
+   "wrap:Video": "89f27b8f",
+   "wrap:Icon slot": "58f36772",
+   "doc:Placeholders(frame)": "281f55e4",
+   "doc:Placeholders/Header": "81e6daf5",
+   "doc:Placeholders/Choosing": "6ec814fe",
+   "doc:Placeholders/Media": "9950079c",
+   "doc:Placeholders/Charts, logos and icons": "702641d2",
+   "doc:Placeholders/Usage": "8edc5116",
+   "doc:Placeholders/Spec": "79eb1b4c"
+  },
+  "Annotations": {
+   "set:Callout": "f16d1f59",
+   "set:Sticky note": "6cfb774e",
+   "set:Tag": "ae26bcd4",
+   "set:Device": "09608176",
+   "frame:Components(shell)": "f88f8da8",
+   "wrap:Callout": "e712b7b4",
+   "wrap:Sticky note": "80097e51",
+   "wrap:Tag": "522f2bdc",
+   "wrap:Device": "786ca9fb",
+   "doc:Annotations(frame)": "94fe33c1",
+   "doc:Annotations/Header": "65ff052c",
+   "doc:Annotations/Callouts and tags": "966065c9",
+   "doc:Annotations/Sticky notes": "297719ff",
+   "doc:Annotations/Devices": "72832fc3",
+   "doc:Annotations/Usage": "4bcc02ea",
+   "doc:Annotations/Spec": "344c308c"
   }
  }
 }

package/figma/library/kit/base.js

@@ -15,7 +15,7 @@ Object.keys(TS).forEach(function (k) { var f = TS[k].fontName; FONTS[f.family +
 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'];
+var PAGES = ['Cover', 'Palettes', 'Color', 'Type', 'Scale', 'Size', 'Elevation, focus and motion', 'Themes', 'Fields', 'Buttons', 'Popups', 'Overlays', 'Disclosure and navigation', 'Display', 'Placeholders', 'Annotations'];
 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; }

package/figma/library/pages/15-cover.js

@@ -6,6 +6,7 @@ var LEAD = 'A desert theme with a violet lead. Every color, size and type style
 var BASE_UI = '1.9';
 var FOUNDATIONS = ['Palettes', 'Color', 'Type', 'Scale', 'Size', 'Elevation, focus and motion', 'Themes'];
 var COMPONENTS = ['Fields', 'Buttons', 'Popups', 'Overlays', 'Disclosure and navigation', 'Display'];
+var MOCKUPS = ['Placeholders', 'Annotations'];
 var PALETTES = ['primary', 'secondary', 'tertiary', 'quaternary', 'neutral'];
 var AF = Object.getPrototypeOf(async function () {}).constructor;
 var L = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'docHelpers'))(figma);
@@ -63,7 +64,7 @@ cov.appendChild(tb); tb.x = 96; tb.y = 120;
 
 // Contents: the page names, by group.
 var ct = AL('HORIZONTAL', { name: 'Contents', itemSpacing: 96 });
-for (var g of [['Foundations', FOUNDATIONS], ['Components', COMPONENTS]]) {
+for (var g of [['Foundations', FOUNDATIONS], ['Components', COMPONENTS], ['Mockups', MOCKUPS]]) {
   var col = AL('VERTICAL', { name: g[0], itemSpacing: 8 }); add(col, [await T(g[0].toUpperCase(), 'eyebrow-condense', 'Theme:text/tertiary')]);
   for (var n of g[1]) add(col, [await T(n, 'subtitle-condense')]);
   add(ct, [col]);

package/figma/library/pages/16-placeholders/01-placeholders.js

@@ -0,0 +1,108 @@
+// Placeholders: Image, Logo, Chart, Map, Video, Icon slot. Stand-ins for content a mockup doesn't
+// have yet. Built only from Theme and Size tokens, so they follow the brand, look and theme.
+// Rebuilds the page's Components column.
+var AF = Object.getPrototypeOf(async function () {}).constructor;
+var C = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'compHelpers'))(figma);
+var v = C.v, paint = C.paint, fill = C.fill, stroke = C.stroke, bind = C.bind, radius = C.radius, AL = C.AL, add = C.add, T = C.T;
+var icon = C.icon, comp = C.comp, textProp = C.textProp, place = C.place, removeOld = C.removeOld;
+await C.page('Placeholders');
+function frameSet(set) { 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; set.clipsContent = false; }
+// Variants in a row, centered on one line; top aligns them instead, so labelSets sees one row.
+function row(set, gap, top) {
+  set.layoutMode = 'NONE'; var x = 32, h = 0;
+  set.children.forEach(function (k) { k.x = x; k.y = 48; x += Math.max(k.width, 64) + gap; h = Math.max(h, k.height); });
+  set.children.forEach(function (k) { k.y = top ? 48 : 48 + Math.round((h - k.height) / 2); });
+  set.resize(x - gap + 32, h + 96); frameSet(set);
+}
+function box(name, w, h) { var c = comp(name); c.layoutMode = 'NONE'; c.resize(w, h); c.clipsContent = true; return c; }
+function center(n, parent) { parent.appendChild(n); n.x = Math.round((parent.width - n.width) / 2); n.y = Math.round((parent.height - n.height) / 2); n.constraints = { horizontal: 'CENTER', vertical: 'CENTER' }; return n; }
+function line(name, d, w, h, colorKey, weight) {
+  var vec = figma.createVector(); vec.name = name; vec.vectorPaths = [{ windingRule: 'NONZERO', data: d }];
+  vec.fills = []; vec.strokes = [paint(colorKey)]; vec.strokeWeight = weight || 1; vec.strokeCap = 'ROUND'; vec.strokeJoin = 'ROUND';
+  return vec;
+}
+var IMG = 'M 2 3 L 14 3 L 14 13 L 2 13 Z M 2 11 L 6 7 L 9 10 L 11 8 L 14 11 M 10.5 5.5 L 11.5 5.5';
+async function chip(d) {
+  var c = figma.createFrame(); c.name = 'Glyph'; c.resize(36, 36); c.cornerRadius = 18; fill(c, 'Theme:surface/canvas');
+  var g = icon('Icon', d, 20, 'Theme:text/tertiary'); c.appendChild(g); g.x = 8; g.y = 8; return c;
+}
+figma.currentPage.children.filter(function (n) { return n.name === 'Components'; }).forEach(function (n) { n.remove(); });
+
+// Image: a crossed box, the oldest wireframe sign for "a picture goes here". Lines scale with the box.
+var RATIOS = [['1:1', 240, 240], ['4:3', 240, 180], ['3:2', 240, 160], ['16:9', 240, 135], ['3:1', 240, 80]], imgs = [];
+for (var r of RATIOS) {
+  var c = box('Ratio=' + r[0], r[1], r[2]); fill(c, 'Theme:fill/subtle'); stroke(c, 'Theme:border/default', 'Size:stroke/default'); radius(c, 'Size:radius/box');
+  for (var d of ['M 0 0 L ' + r[1] + ' ' + r[2], 'M ' + r[1] + ' 0 L 0 ' + r[2]]) { var l = line('Cross', d, r[1], r[2], 'Theme:border/strong'); c.appendChild(l); l.x = 0; l.y = 0; l.constraints = { horizontal: 'SCALE', vertical: 'SCALE' }; }
+  center(await chip(IMG), c);
+  imgs.push(c);
+}
+var imgSet = figma.combineAsVariants(imgs, figma.currentPage); imgSet.name = 'Image'; row(imgSet, 40, true);
+imgSet.description = 'A picture goes here: a crossed box at five ratios. Resize freely; the cross scales and the glyph stays centered. fill/subtle, border/default, radius/box.';
+place(imgSet);
+
+// Logo
+var logos = [];
+for (var s of [['Wordmark', 160, 40], ['Mark', 40, 40]]) {
+  var c = comp('Shape=' + s[0]); c.primaryAxisAlignItems = 'CENTER'; c.counterAxisAlignItems = 'CENTER';
+  c.resize(s[1], s[2]); c.primaryAxisSizingMode = 'FIXED'; c.counterAxisSizingMode = 'FIXED';
+  stroke(c, 'Theme:border/strong', 'Size:stroke/default'); c.dashPattern = [4, 3]; radius(c, 'Size:radius/minimal');
+  var t = await T(s[0] === 'Mark' ? 'L' : 'LOGO', 'eyebrow-condense', 'Theme:text/tertiary'); t.name = 'Label'; add(c, [t]);
+  logos.push(c);
+}
+var logoSet = figma.combineAsVariants(logos, figma.currentPage); logoSet.name = 'Logo'; row(logoSet, 40);
+logoSet.description = 'Where a logo goes: a dashed outline so it never reads as a real mark. border/strong, radius/minimal, eyebrow-condense.';
+place(logoSet);
+
+// Chart
+var charts = [];
+for (var kind of ['Bar', 'Line', 'Donut']) {
+  var c = box('Type=' + kind, 240, 160); fill(c, 'Theme:fill/subtle'); radius(c, 'Size:radius/box');
+  if (kind === 'Bar') {
+    var H = [52, 88, 70, 112, 64, 96];
+    H.forEach(function (h, i) { var b = figma.createRectangle(); b.name = 'Bar'; b.resize(20, h); b.x = 24 + i * 34; b.y = 136 - h; fill(b, i === 3 ? 'Theme:fill/stronger' : 'Theme:fill/strong'); b.topLeftRadius = b.topRightRadius = 3; b.constraints = { horizontal: 'SCALE', vertical: 'SCALE' }; c.appendChild(b); });
+  } else if (kind === 'Line') {
+    for (var y of [40, 72, 104, 136]) { var g = line('Grid', 'M 0 0 L 192 0', 192, 0, 'Theme:border/subtle'); c.appendChild(g); g.x = 24; g.y = y; g.constraints = { horizontal: 'SCALE', vertical: 'SCALE' }; }
+    var p = line('Series', 'M 0 70 L 38 52 L 76 64 L 114 30 L 152 42 L 192 8', 192, 70, 'Theme:text/secondary', 2); c.appendChild(p); p.x = 24; p.y = 48; p.constraints = { horizontal: 'SCALE', vertical: 'SCALE' };
+  } else {
+    var seg = [['Theme:fill/stronger', 0, 2.4], ['Theme:fill/strong', 2.4, 4.4], ['Theme:fill/default', 4.4, 2 * Math.PI]];
+    seg.forEach(function (s) { var e = figma.createEllipse(); e.name = 'Segment'; e.resize(112, 112); e.x = 64; e.y = 24; e.arcData = { startingAngle: s[1] - Math.PI / 2, endingAngle: s[2] - Math.PI / 2, innerRadius: 0.6 }; fill(e, s[0]); e.constraints = { horizontal: 'CENTER', vertical: 'CENTER' }; c.appendChild(e); });
+  }
+  charts.push(c);
+}
+var chartSet = figma.combineAsVariants(charts, figma.currentPage); chartSet.name = 'Chart'; row(chartSet, 40);
+chartSet.description = 'A chart goes here: bars, a line or a donut in grays, so nobody mistakes it for real data. fill/subtle background, fill/default to fill/stronger marks.';
+place(chartSet);
+
+// Map
+var m = box('Style=Default', 240, 160); fill(m, 'Theme:fill/subtle'); radius(m, 'Size:radius/box');
+var roads = ['M 0 110 L 90 96 L 150 120 L 240 100', 'M 70 0 L 92 96 L 104 160', 'M 150 120 L 176 0', 'M 0 40 L 240 56'];
+roads.forEach(function (d, i) { var r = line('Road', d, 240, 160, 'Theme:surface/canvas', i < 2 ? 6 : 3); m.appendChild(r); var xs = [], ys = []; d.replace(/(-?[\d.]+) (-?[\d.]+)/g, function (q, x, y) { xs.push(+x); ys.push(+y); }); r.x = Math.min.apply(null, xs); r.y = Math.min.apply(null, ys); r.constraints = { horizontal: 'SCALE', vertical: 'SCALE' }; });
+var pin = icon('Pin', 'M 8 14.5 C 8 14.5 3 9.5 3 6.2 C 3 3.3 5.2 1.2 8 1.2 C 10.8 1.2 13 3.3 13 6.2 C 13 9.5 8 14.5 8 14.5 Z M 8 4.7 L 8 7.3', 28, 'Theme:text/primary', 1.6);
+m.appendChild(pin); pin.x = 106; pin.y = 58; pin.constraints = { horizontal: 'CENTER', vertical: 'CENTER' };
+var mapSet = figma.combineAsVariants([m], figma.currentPage); mapSet.name = 'Map'; row(mapSet, 40);
+mapSet.description = 'A map goes here: roads on a gray ground and a pin. fill/subtle, surface/canvas roads, text/primary pin.';
+place(mapSet);
+
+// Video
+var vid = box('Style=Default', 240, 135); fill(vid, 'Theme:surface/inverse'); radius(vid, 'Size:radius/box');
+var play = figma.createFrame(); play.name = 'Play'; play.resize(44, 44); play.cornerRadius = 22; fill(play, 'Theme:surface/canvas');
+var tri = figma.createVector(); tri.name = 'Triangle'; tri.vectorPaths = [{ windingRule: 'NONZERO', data: 'M 0 0 L 14 8 L 0 16 Z' }]; fill(tri, 'Theme:text/primary'); play.appendChild(tri); tri.x = 17; tri.y = 14;
+center(play, vid);
+var track = figma.createRectangle(); track.name = 'Track'; track.resize(216, 4); track.x = 12; track.y = 119; track.cornerRadius = 2; fill(track, 'Theme:text/tertiary'); track.constraints = { horizontal: 'STRETCH', vertical: 'MAX' }; vid.appendChild(track);
+var prog = figma.createRectangle(); prog.name = 'Played'; prog.resize(72, 4); prog.x = 12; prog.y = 119; prog.cornerRadius = 2; fill(prog, 'Theme:text/on-inverse'); prog.constraints = { horizontal: 'SCALE', vertical: 'MAX' }; vid.appendChild(prog);
+var vidSet = figma.combineAsVariants([vid], figma.currentPage); vidSet.name = 'Video'; row(vidSet, 40);
+vidSet.description = 'A video goes here: the inverse surface, a play button and a progress track. surface/inverse, surface/canvas, text/on-inverse.';
+place(vidSet);
+
+// Icon slot
+var slots = [];
+for (var z of ['minimize', 'condense', 'base', 'magnify', 'maximize']) {
+  var c = box('Size=' + z, 16, 16); bind(c, ['width', 'height'], 'Size:icon-size/' + z);
+  stroke(c, 'Theme:border/strong', 1); c.dashPattern = [2, 2]; radius(c, 'Size:radius/minimal'); c.clipsContent = false;
+  var x = line('Cross', 'M 0 0 L 16 16 M 16 0 L 0 16', 16, 16, 'Theme:border/default'); c.appendChild(x); x.x = 0; x.y = 0; x.constraints = { horizontal: 'SCALE', vertical: 'SCALE' };
+  slots.push(c);
+}
+var slotSet = figma.combineAsVariants(slots, figma.currentPage); slotSet.name = 'Icon slot'; row(slotSet, 32);
+slotSet.description = 'An icon goes here, at the icon-size steps. Swap it for a real icon later. border/strong dashed, radius/minimal.';
+place(slotSet);
+return { built: ['Image', 'Logo', 'Chart', 'Map', 'Video', 'Icon slot'], page: figma.currentPage.id };

package/figma/library/pages/16-placeholders/02-labels.js

@@ -0,0 +1,12 @@
+// Placeholders: a header and column labels for each set. Run after 01.
+var AF = Object.getPrototypeOf(async function () {}).constructor;
+var C = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'compHelpers'))(figma);
+await C.page('Placeholders');
+return await C.labelSets({
+  Image: 'A crossed box at five ratios: a picture goes here. Resize freely; the glyph stays centered.',
+  Logo: 'A dashed outline where a logo goes, so it never reads as a real mark.',
+  Chart: 'Bars, a line or a donut in grays, so nobody mistakes it for real data.',
+  Map: 'Roads on a gray ground and a pin: a map goes here.',
+  Video: 'The inverse surface, a play button and a progress track: a video goes here.',
+  'Icon slot': 'An icon goes here, at the five icon-size steps.'
+});

package/figma/library/pages/16-placeholders/03-doc.js

@@ -0,0 +1,28 @@
+// Placeholders doc frame. Run after every Placeholders set is built and labelled.
+var AF = Object.getPrototypeOf(async function () {}).constructor;
+var L = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'docHelpers'))(figma);
+await L.page('Placeholders');
+var K = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'docKit'))(figma);
+var AL = L.AL, add = L.add, T = L.T, section = L.section, hrow = L.hrow, divider = L.divider, inst = K.inst, stage = K.stage, captioned = K.captioned, notes = K.notes, usage = K.usage;
+var doc = await L.docFrame('Placeholders', 'MOCKUPS', 'Placeholders', 'Stand-ins for content a mockup does not have yet: pictures, logos, charts, maps, video and icons. They are drawn only with theme tokens, so they follow the brand, the look and light or dark. Components sit to the right.');
+doc.x = 0; doc.y = 400;
+var pick = await section(doc, 'Choosing', 'Pick the one that says what will go there, so reviewers read the layout, not the art.');
+var picks = [['A photo or illustration', 'Image', 'Pick the ratio the real picture will have.'], ['A brand or partner mark', 'Logo', 'Wordmark for a header, Mark for tight spots.'], ['Numbers shown as a graphic', 'Chart', 'Bar, Line or Donut, in grays so nobody reads the data.'], ['A place', 'Map', 'Stretch it; the roads scale with the box.'], ['Something that plays', 'Video', 'Sits on the inverse surface like a real player.'], ['An icon not chosen yet', 'Icon slot', 'At the icon-size step the real icon will use.']];
+var pt = AL('VERTICAL', { name: 'Picker' }); add(pick, [pt]); pt.layoutSizingHorizontal = 'FILL';
+for (var i = 0; i < picks.length; i++) { var r = hrow(pt); divider(r); add(r, [await T(picks[i][0], 'body-base', 'Theme:text/primary', 380), await T(picks[i][1], 'subtitle-base', 'Theme:text/accent', 200), await T(picks[i][2], 'body-condense', 'Theme:text/secondary', 520)]); }
+// Placeholders sit on fill/subtle themselves, so their stages use the page color with an edge.
+function plain(parent, name) { var st = stage(parent, name); L.fill(st, 'Theme:surface/canvas'); L.stroke(st, 'Theme:border/subtle', 1); return st; }
+var media = await section(doc, 'Media', 'A crossed box is the oldest sign for "a picture goes here". Image comes in five ratios; resize any of them and the cross scales while the glyph stays centered. Map and Video stretch the same way.');
+var s1 = plain(media, 'Images');
+for (var q of ['1:1', '4:3', '16:9', '3:1']) add(s1, [await captioned(inst('Image', 'Ratio=' + q), q)]);
+var s1b = plain(media, 'Map and video');
+add(s1b, [await captioned(inst('Map', 'Style=Default'), 'Map'), await captioned(inst('Video', 'Style=Default'), 'Video')]);
+var marks = await section(doc, 'Charts, logos and icons', 'Charts use the fill steps so they read as shapes, never as real numbers. Logos are dashed outlines so they never pass for a real mark. Icon slots hold the place at each icon size.');
+var s2 = plain(marks, 'Charts');
+for (var c of ['Bar', 'Line', 'Donut']) add(s2, [await captioned(inst('Chart', 'Type=' + c), c)]);
+var s2b = plain(marks, 'Logos and icons'); s2b.counterAxisAlignItems = 'CENTER';
+add(s2b, [await captioned(inst('Logo', 'Shape=Wordmark'), 'Wordmark'), await captioned(inst('Logo', 'Shape=Mark'), 'Mark')]);
+for (var z of ['minimize', 'condense', 'base', 'magnify', 'maximize']) add(s2b, [await captioned(inst('Icon slot', 'Size=' + z), z)]);
+await usage(doc, ['Mockups and wireframes before the real content exists.', 'Showing the size and ratio the real content will need.'], ['Shipping them in a product. They are for design files only.', 'Lorem ipsum text. Write real words, or use skeleton lines.']);
+await notes(doc, [['Ground', 'fill/subtle · radius/box', 'Quiet, so the layout leads.'], ['Edge', 'border/default · stroke/default', 'Shows the box without weight.'], ['Cross and outlines', 'border/strong', 'Dashed for logos and icon slots.'], ['Marks', 'fill/default · fill/strong · fill/stronger', 'Chart bars and segments.'], ['Video', 'surface/inverse · text/on-inverse', 'Reads as a player in any theme.'], ['Icon slot', 'icon-size/*', 'The same steps as real icons.']]);
+return { id: doc.id, h: Math.round(doc.height), overflow: K.overflow(doc) };

package/figma/library/pages/17-annotations/01-annotations.js

@@ -0,0 +1,93 @@
+// Annotations: Callout, Sticky note, Tag, Device. Marks for reviews and handoff on any mockup.
+// Callouts, tags and notes use fixed colors on purpose, so they never read as part of the design.
+// Device frames use theme tokens, so they follow the look. Rebuilds the page's Components column.
+var AF = Object.getPrototypeOf(async function () {}).constructor;
+var C = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'compHelpers'))(figma);
+var v = C.v, paint = C.paint, fill = C.fill, stroke = C.stroke, bind = C.bind, radius = C.radius, AL = C.AL, add = C.add, T = C.T;
+var comp = C.comp, textProp = C.textProp, place = C.place, removeOld = C.removeOld;
+await C.page('Annotations');
+function hex(h) { return { r: parseInt(h.slice(1, 3), 16) / 255, g: parseInt(h.slice(3, 5), 16) / 255, b: parseInt(h.slice(5, 7), 16) / 255 }; }
+function solid(n, h) { n.fills = [{ type: 'SOLID', color: hex(h) }]; return n; }
+var MARK = '#2F6BFF', MARK_TEXT = '#1F4FD1', MARK_TINT = '#EAF0FF', NOTE_TEXT = '#26231F';
+function frameSet(set) { 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; set.clipsContent = false; }
+function row(set, gap) {
+  set.layoutMode = 'NONE'; var x = 32, h = 0;
+  set.children.forEach(function (k) { k.x = x; k.y = 48; x += k.width + gap; h = Math.max(h, k.height); });
+  set.children.forEach(function (k) { k.y = 48; });
+  set.resize(x - gap + 32, h + 96); frameSet(set);
+}
+figma.currentPage.children.filter(function (n) { return n.name === 'Components'; }).forEach(function (n) { n.remove(); });
+
+// Callout: a numbered dot, or a dot with a short label
+var calls = [];
+for (var kind of ['Number', 'Label']) {
+  var c = comp('Type=' + kind); c.counterAxisAlignItems = 'CENTER'; c.itemSpacing = 8;
+  if (kind === 'Label') { solid(c, MARK); c.cornerRadius = 14; c.paddingLeft = 2; c.paddingRight = 12; c.paddingTop = c.paddingBottom = 2; }
+  var dot = AL('HORIZONTAL', { name: 'Dot', primaryAxisAlignItems: 'CENTER', counterAxisAlignItems: 'CENTER' });
+  dot.resize(24, 24); dot.primaryAxisSizingMode = 'FIXED'; dot.counterAxisSizingMode = 'FIXED'; dot.cornerRadius = 12;
+  solid(dot, kind === 'Label' ? '#FFFFFF' : MARK);
+  var n = await T('1', 'subtitle-condense'); n.name = 'Number'; solid(n, kind === 'Label' ? MARK_TEXT : '#FFFFFF'); add(dot, [n]);
+  add(c, [dot]);
+  if (kind === 'Label') { var l = await T('Opens the date picker', 'label-base'); l.name = 'Label'; solid(l, '#FFFFFF'); add(c, [l]); }
+  calls.push(c);
+}
+var callSet = figma.combineAsVariants(calls, figma.currentPage); callSet.name = 'Callout'; row(callSet, 40);
+textProp(callSet, 'Number', '1', 'Number'); textProp(callSet, 'Label', 'Opens the date picker', 'Label');
+callSet.description = 'Number a spot in a wireframe and explain it in the notes, or label it right there. A fixed blue that no theme uses, so it never reads as part of the design.';
+place(callSet);
+
+// Sticky note
+var NOTES = { Yellow: '#FFF0A6', Pink: '#FFD5E5', Blue: '#D6E6FF' }, stickies = [];
+for (var col in NOTES) {
+  var c = comp('Color=' + col, 'VERTICAL'); c.itemSpacing = 6; c.paddingTop = c.paddingBottom = c.paddingLeft = c.paddingRight = 16;
+  c.resize(200, 120); c.counterAxisSizingMode = 'FIXED'; c.primaryAxisSizingMode = 'AUTO'; solid(c, NOTES[col]); c.cornerRadius = 2;
+  c.effects = [{ type: 'DROP_SHADOW', color: { r: 0, g: 0, b: 0, a: 0.12 }, offset: { x: 0, y: 2 }, radius: 6, spread: 0, visible: true, blendMode: 'NORMAL' }];
+  var t = await T('Question', 'subtitle-base'); t.name = 'Title'; solid(t, NOTE_TEXT);
+  var b = await T('Do we need a guest checkout here, or can people book without an account?', 'body-condense'); b.name = 'Note'; solid(b, NOTE_TEXT);
+  add(c, [t, b]); t.layoutSizingHorizontal = 'FILL'; b.layoutSizingHorizontal = 'FILL'; b.textAutoResize = 'HEIGHT';
+  stickies.push(c);
+}
+var stickySet = figma.combineAsVariants(stickies, figma.currentPage); stickySet.name = 'Sticky note'; row(stickySet, 32);
+textProp(stickySet, 'Title', 'Question', 'Title'); textProp(stickySet, 'Note', 'Do we need a guest checkout here, or can people book without an account?', 'Note');
+stickySet.description = 'A note for reviewers: questions, ideas, decisions. Pick a color per person or per kind of note. Fixed colors, outside the theme.';
+place(stickySet);
+
+// Tag
+var tag = comp('Style=Default'); tag.counterAxisAlignItems = 'CENTER'; tag.paddingLeft = tag.paddingRight = 8; tag.paddingTop = tag.paddingBottom = 2; tag.cornerRadius = 4;
+solid(tag, MARK_TINT); tag.strokes = [{ type: 'SOLID', color: hex(MARK) }]; tag.strokeWeight = 1; tag.strokeAlign = 'INSIDE';
+var tl = await T('TBD', 'eyebrow-condense'); tl.name = 'Label'; solid(tl, MARK_TEXT); add(tag, [tl]);
+var tagSet = figma.combineAsVariants([tag], figma.currentPage); tagSet.name = 'Tag'; row(tagSet, 40);
+var tk = tagSet.addComponentProperty('Label', 'TEXT', 'TBD'); tl.componentPropertyReferences = { characters: tk };
+tagSet.description = 'Mark something as not settled: TBD, Question, Changed, Idea. Same fixed blue as callouts.';
+place(tagSet);
+
+// Device: phone, tablet and desktop frames with a Content area to design in
+var DEV = [['Phone', 390, 844, 44, 40], ['Tablet', 834, 1194, 28, 24], ['Desktop', 1440, 900, 48, 10]], devs = [];
+for (var d of DEV) {
+  var c = comp('Device=' + d[0], 'VERTICAL'); c.resize(d[1], d[2]); c.primaryAxisSizingMode = 'FIXED'; c.counterAxisSizingMode = 'FIXED'; c.clipsContent = true;
+  fill(c, 'Theme:surface/canvas'); stroke(c, 'Theme:border/strong', 'Size:stroke/default'); c.cornerRadius = d[4];
+  var bar = AL('HORIZONTAL', { name: d[0] === 'Desktop' ? 'Browser bar' : 'Status bar', counterAxisAlignItems: 'CENTER', itemSpacing: 8, paddingLeft: d[0] === 'Desktop' ? 16 : 28, paddingRight: d[0] === 'Desktop' ? 16 : 28 });
+  bar.resize(d[1], d[3]); bar.counterAxisSizingMode = 'FIXED'; add(c, [bar]); bar.layoutSizingHorizontal = 'FILL';
+  if (d[0] === 'Desktop') {
+    fill(bar, 'Theme:surface/tray'); bar.strokes = [paint('Theme:border/default')]; bar.strokeTopWeight = bar.strokeLeftWeight = bar.strokeRightWeight = 0; bar.strokeBottomWeight = 1;
+    for (var q = 0; q < 3; q++) { var e = figma.createEllipse(); e.name = 'Dot'; e.resize(12, 12); fill(e, 'Theme:fill/strong'); add(bar, [e]); }
+    var url = AL('HORIZONTAL', { name: 'Address', counterAxisAlignItems: 'CENTER', paddingLeft: 12, paddingRight: 12 }); url.resize(560, 28); url.counterAxisSizingMode = 'FIXED'; url.primaryAxisSizingMode = 'FIXED';
+    fill(url, 'Theme:surface/canvas'); stroke(url, 'Theme:border/default', 1); radius(url, 'Size:radius/control');
+    add(url, [await T('example.com', 'body-condense', 'Theme:text/tertiary')]); var sp = AL('HORIZONTAL', { name: 'Spacer' }); add(bar, [sp, url]); sp.resize(160, 1);
+  } else {
+    bar.primaryAxisAlignItems = 'SPACE_BETWEEN';
+    var time = await T('9:41', 'subtitle-condense'); var ind = AL('HORIZONTAL', { name: 'Indicators', itemSpacing: 4, counterAxisAlignItems: 'CENTER' });
+    [[16, 10], [14, 10], [24, 11]].forEach(function (s) { var r = figma.createRectangle(); r.resize(s[0], s[1]); r.cornerRadius = 3; fill(r, 'Theme:text/primary'); add(ind, [r]); });
+    add(bar, [time, ind]);
+  }
+  var content = AL('VERTICAL', { name: 'Content' }); add(c, [content]); content.layoutSizingHorizontal = 'FILL'; content.layoutSizingVertical = 'FILL';
+  if (d[0] !== 'Desktop') {
+    var home = AL('HORIZONTAL', { name: 'Home indicator', primaryAxisAlignItems: 'CENTER', counterAxisAlignItems: 'CENTER' }); home.resize(d[1], 34); home.counterAxisSizingMode = 'FIXED';
+    var hb = figma.createRectangle(); hb.name = 'Bar'; hb.resize(134, 5); hb.cornerRadius = 3; fill(hb, 'Theme:text/primary'); add(home, [hb]); add(c, [home]); home.layoutSizingHorizontal = 'FILL';
+  }
+  devs.push(c);
+}
+var devSet = figma.combineAsVariants(devs, figma.currentPage); devSet.name = 'Device'; row(devSet, 80);
+devSet.description = 'A screen to sketch in: phone (390×844), tablet (834×1194) and desktop browser (1440×900). Put your layout in Content. Chrome uses surface/canvas, surface/tray and border/strong, so it follows the look.';
+place(devSet);
+return { built: ['Callout', 'Sticky note', 'Tag', 'Device'], page: figma.currentPage.id };

package/figma/library/pages/17-annotations/02-labels.js

@@ -0,0 +1,10 @@
+// Annotations: a header and column labels for each set. Run after 01.
+var AF = Object.getPrototypeOf(async function () {}).constructor;
+var C = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'compHelpers'))(figma);
+await C.page('Annotations');
+return await C.labelSets({
+  Callout: 'Number a spot and explain it in the notes, or label it in place. Fixed blue, outside the theme.',
+  'Sticky note': 'Questions and ideas for reviewers. A color per person or per kind of note.',
+  Tag: 'Marks something as not settled. Change the label: TBD, Question, Changed, Idea.',
+  Device: 'Phone, tablet and desktop browser frames. Put the layout in Content.'
+});

package/figma/library/pages/17-annotations/03-doc.js

@@ -0,0 +1,22 @@
+// Annotations doc frame. Run after every Annotations set is built and labelled.
+var AF = Object.getPrototypeOf(async function () {}).constructor;
+var L = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'docHelpers'))(figma);
+await L.page('Annotations');
+var K = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'docKit'))(figma);
+var add = L.add, section = L.section, inst = K.inst, stage = K.stage, captioned = K.captioned, notes = K.notes, usage = K.usage;
+var doc = await L.docFrame('Annotations', 'MOCKUPS', 'Annotations', 'Marks for reviews and handoff: numbered callouts, sticky notes, tags for open questions, and device frames to design in. Callouts, notes and tags use fixed colors that no theme uses, so markup never reads as part of the design. Components sit to the right.');
+doc.x = 0; doc.y = 400;
+var mk = await section(doc, 'Callouts and tags', 'Number a spot and explain it in notes beside the frame, or label it in place. Tag anything not settled yet.');
+var s1 = stage(mk, 'Marks'); s1.counterAxisAlignItems = 'CENTER';
+add(s1, [await captioned(inst('Callout', 'Type=Number'), 'Number'), await captioned(inst('Callout', 'Type=Label'), 'Label')]);
+for (var w of ['TBD', 'Question', 'Changed']) add(s1, [await captioned(inst('Tag', 'Style=Default', { Label: w }), w)]);
+var st = await section(doc, 'Sticky notes', 'Questions, ideas and decisions for reviewers. Give each person or each kind of note its own color.');
+var s2 = stage(st, 'Notes');
+for (var c of ['Yellow', 'Pink', 'Blue']) add(s2, [await captioned(inst('Sticky note', 'Color=' + c), c)]);
+var dv = await section(doc, 'Devices', 'Phone (390×844), tablet (834×1194) and desktop browser (1440×900). Put the layout in the Content frame. The chrome uses theme tokens, so it follows the look.');
+var s3 = stage(dv, 'Devices'); s3.counterAxisAlignItems = 'MAX';
+var ph = inst('Device', 'Device=Phone'); ph.rescale(0.5); var tb = inst('Device', 'Device=Tablet'); tb.rescale(0.35); var dk = inst('Device', 'Device=Desktop'); dk.rescale(0.4);
+add(s3, [await captioned(ph, 'Phone, at 50%'), await captioned(tb, 'Tablet, at 35%'), await captioned(dk, 'Desktop, at 40%')]);
+await usage(doc, ['Reviews, handoff notes and open questions.', 'Numbered callouts with the explanation beside the frame.'], ['Theme colors for markup. It would read as part of the design.', 'Notes left in a file after the decision is made.']);
+await notes(doc, [['Mark', '#2F6BFF fill · #1F4FD1 text', 'A fixed blue, outside every theme.'], ['Tag', '#EAF0FF ground · #2F6BFF edge', 'Same blue, quieter.'], ['Notes', '#FFF0A6 · #FFD5E5 · #D6E6FF', 'Paper colors with #26231F text.'], ['Device', 'surface/canvas · surface/tray · border/strong', 'Follows the look and theme.']]);
+return { id: doc.id, h: Math.round(doc.height), overflow: K.overflow(doc) };

package/figma/library/run-order.json

@@ -16,6 +16,8 @@
     { "page": "Overlays", "files": ["pages/12-overlays/01-overlays.js", "pages/12-overlays/02-labels.js", "pages/12-overlays/03-doc.js"] },
     { "page": "Disclosure and navigation", "files": ["pages/13-disclosure/01-disclosure.js", "pages/13-disclosure/02-collapsible.js", "pages/13-disclosure/03-labels.js", "pages/13-disclosure/04-doc.js"] },
     { "page": "Display", "files": ["pages/14-display/01-display.js", "pages/14-display/02-more-display.js", "pages/14-display/03-labels.js", "pages/14-display/04-doc.js"] },
+    { "page": "Placeholders", "files": ["pages/16-placeholders/01-placeholders.js", "pages/16-placeholders/02-labels.js", "pages/16-placeholders/03-doc.js"] },
+    { "page": "Annotations", "files": ["pages/17-annotations/01-annotations.js", "pages/17-annotations/02-labels.js", "pages/17-annotations/03-doc.js"] },
     { "page": "Cover", "files": ["pages/15-cover.js"] }
   ]
 }

package/figma/plugin/code.js

@@ -346,6 +346,25 @@ async function loomiereMigrate(dryRun) {
   return renamed;
 }
 
+async function loomiereLoadFonts(data) {
+  var families = {};
+  (data.textStyles || []).forEach(function (t) {
+    if (t.family) families[t.family] = true;
+  });
+  var want = [];
+  (await figma.getLocalTextStylesAsync()).forEach(function (s) {
+    want.push(s.fontName);
+  });
+  (await figma.listAvailableFontsAsync()).forEach(function (f) {
+    if (families[f.fontName.family]) want.push(f.fontName);
+  });
+  for (var i = 0; i < want.length; i++) {
+    try {
+      await figma.loadFontAsync(want[i]);
+    } catch (e) {}
+  }
+}
+
 async function loomiereSync(data, options) {
   options = options || {};
   if (!data || data.format !== "loomiere-figma")
@@ -354,6 +373,9 @@ async function loomiereSync(data, options) {
     );
   var dryRun = !!options.dryRun;
   var warnings = [];
+  // Text styles bind fontFamily to a variable, so changing that variable needs the
+  // new family loaded in every style the file's text styles use, and the old ones too.
+  if (!dryRun) await loomiereLoadFonts(data);
   var report = {
     dryRun: dryRun,
     brand: data.brand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scattered-light/loomiere",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Turns a small brand file into a full design token theme: OKLCH color ramps, a type scale, light, dark and high-contrast modes, plus Tailwind, MUI, Chakra, AG Grid and Figma exports.",
   "keywords": ["design-tokens", "theme", "style-dictionary", "dtcg", "oklch", "base-ui", "ag-grid", "tailwind"],
   "repository": {

package/tokens/README.md

@@ -66,6 +66,7 @@ A look is another way the same brand can look: an old and a new brand, a quiet a
 - It is merged over the brand: objects merge key by key and lists replace. A palette, a pair, a concept, an emphasis or status entry, or a font's metrics replaces the brand's whole entry, so a look's palette never keeps keys from the brand's.
 - `tokens` picks a value for any semantic or component token, for what the brand inputs can't say (square buttons, a thicker focus ring). It works at the top of the brand file too.
 - Every look has the same tokens; only their values change. Components, Figma bindings and code written against one look work in all of them. Pair names and role rules must match across looks; the build says so if they don't.
+- A look's `tokens` can point a token at something else in that look only, such as Highlighter's selected table rows at the highlighter yellow: `"tokens": { "table.row-selected": "{scope.secondary.soft-hover}" }`. Point at a scope slot (`{scope.<palette>.<slot>}`) or a semantic token rather than a palette step, so the value still changes with light, dark and high contrast. Brand pair classes pick up the look's value too.
 
 In CSS a look is `data-look="<name>"` on the root element, next to `data-theme`. With no `data-look` the brand's own look applies. `tokens.css` holds one `[data-look]` block with only the variables that change, plus that look's dark, high contrast and color vision blocks. The contrast check runs on every look, and `tokens.json` lists the looks under `looks` with what each one changes. In Figma each look is a mode of the Brand collection (see [figma/README.md](../figma/README.md)), and Storybook has a Look toolbar.