@scattered-light/loomiere 0.3.0 → 0.4.1

package/exporters/mui.mjs

@@ -13,19 +13,19 @@ import { raw, styleKit, toSource } from './component-styles.mjs';
 const MUI_GREYS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
 /** MUI typography variant → text style. */
 const TYPE = {
-  h1: 'maximize-4xl',
-  h2: 'maximize-3xl',
-  h3: 'maximize-2xl',
-  h4: 'maximize-xl',
-  h5: 'maximize-lg',
-  h6: 'maximize-md',
-  subtitle1: 'magnify',
-  subtitle2: 'base-label',
-  body1: 'base',
-  body2: 'condense',
-  caption: 'minimize',
-  button: 'base-trigger',
-  overline: 'condense-subtitle-label',
+  h1: 'title-maximize',
+  h2: 'title-amplify',
+  h3: 'title-magnify',
+  h4: 'title-base',
+  h5: 'title-condense',
+  h6: 'title-condense',
+  subtitle1: 'body-magnify',
+  subtitle2: 'label-base',
+  body1: 'body-base',
+  body2: 'body-condense',
+  caption: 'body-minimize',
+  button: 'trigger-base',
+  overline: 'eyebrow-condense',
 };
 /** MUI size → control tier. */
 const SIZE = { small: 'sm', medium: 'md', large: 'lg' };
@@ -105,7 +105,7 @@ export default {
         paddingBlock: 0,
         paddingInline: v(`control-padding-inline${tier === 'md' ? '' : `-${tier}`}`),
       },
-      ...text(tier === 'sm' ? 'condense' : tier === 'lg' ? 'magnify' : 'base'),
+      ...text(tier === 'sm' ? 'body-condense' : tier === 'lg' ? 'body-magnify' : 'body-base'),
     });
 
     const components = {
@@ -183,7 +183,7 @@ export default {
         defaultProps: { shrink: true },
         styleOverrides: {
           root: {
-            ...text('base-label'),
+            ...text('label-base'),
             position: 'relative',
             transform: 'none',
             maxWidth: 'none',
@@ -199,7 +199,7 @@ export default {
       MuiFormLabel: {
         styleOverrides: {
           root: {
-            ...text('base-label'),
+            ...text('label-base'),
             color: v('text-primary'),
             '&.Mui-focused, &.Mui-error': { color: v('text-primary') },
             '&.Mui-disabled': { color: v('text-disabled') },
@@ -209,16 +209,16 @@ export default {
       MuiFormHelperText: {
         styleOverrides: {
           root: {
-            ...text('condense'),
+            ...text('body-condense'),
             margin: `calc(${v('field-gap')} + ${v('field-message-spacing')}) 0 0`,
             color: v('text-secondary'),
-            '&.Mui-error': { ...text('base-label'), color: v('status-error') },
+            '&.Mui-error': { ...text('label-base'), color: v('status-error') },
           },
         },
       },
       MuiInputBase: {
         styleOverrides: {
-          root: { ...text('base'), color: v('field-color') },
+          root: { ...text('body-base'), color: v('field-color') },
           input: { '&::placeholder': k.fieldStates.placeholder, '&.Mui-disabled': { WebkitTextFillColor: v('field-color-disabled') } },
         },
       },
@@ -280,7 +280,7 @@ export default {
           },
         },
       },
-      MuiListSubheader: { styleOverrides: { root: { ...k.groupLabel, margin: 0, lineHeight: v('font-condense-subtitle-label-line-height') } } },
+      MuiListSubheader: { styleOverrides: { root: { ...k.groupLabel, margin: 0, lineHeight: v('font-eyebrow-condense-line-height') } } },
       MuiDivider: {
         styleOverrides: {
           root: {
@@ -300,8 +300,8 @@ export default {
             '&[aria-selected="true"], &[aria-selected="true"].Mui-focused': k.itemStates.selected,
             '&[aria-disabled="true"]': k.itemStates.disabled,
           },
-          groupLabel: { ...k.groupLabel, lineHeight: v('font-condense-subtitle-label-line-height') },
-          noOptions: { ...text('condense'), color: v('text-tertiary'), textAlign: 'center', paddingBlock: v('popup-empty-padding-block') },
+          groupLabel: { ...k.groupLabel, lineHeight: v('font-eyebrow-condense-line-height') },
+          noOptions: { ...text('body-condense'), color: v('text-tertiary'), textAlign: 'center', paddingBlock: v('popup-empty-padding-block') },
           clearIndicator: { ...k.iconButton, '&:hover': k.iconButtonHover },
           popupIndicator: { color: v('text-tertiary') },
           tag: { margin: v('space-0-5') },
@@ -318,9 +318,9 @@ export default {
             color: v('text-primary'),
             '&.Mui-disabled': { cursor: 'not-allowed' },
             // A switch's label uses the label style, as SwitchLabel does.
-            '&:has(.MuiSwitch-root) .MuiFormControlLabel-label': text('base-label'),
+            '&:has(.MuiSwitch-root) .MuiFormControlLabel-label': text('label-base'),
           },
-          label: { ...text('base'), '&.Mui-disabled': { color: v('text-disabled') } },
+          label: { ...text('body-base'), '&.Mui-disabled': { color: v('text-disabled') } },
           // A switch's label is the label style, as SwitchLabel is.
 
         },
@@ -416,7 +416,7 @@ export default {
             border: `${v('check-border-width')} solid ${v('check-border-color')}`,
             transition: `background-color ${v('duration-normal')} ${v('easing-in-out')}`,
             '&::before': {
-              ...text('condense-subtitle-label'),
+              ...text('eyebrow-condense'),
               content: '"off"',
               position: 'absolute',
               insetBlock: 0,
@@ -464,7 +464,7 @@ export default {
           },
           mark: { width: v('stroke-emphasis'), height: `calc(${v('gauge-height-sm')} * 2)`, background: v('fill-strong'), borderRadius: v('radius-pill') },
           markActive: { background: v('fill-strong'), opacity: 1 },
-          valueLabel: { ...text('condense'), background: v('surface-inverse'), color: v('text-on-inverse-surface'), borderRadius: v('radius-chrome') },
+          valueLabel: { ...text('body-condense'), background: v('surface-inverse'), color: v('text-on-inverse-surface'), borderRadius: v('radius-chrome') },
         },
       },
 
@@ -478,7 +478,7 @@ export default {
       MuiTab: {
         styleOverrides: {
           root: {
-            ...text('base'),
+            ...text('body-base'),
             textTransform: 'none',
             minHeight: 0,
             minWidth: 0,
@@ -487,7 +487,7 @@ export default {
             opacity: 1,
             transition: v('transition-button'),
             '&:hover:not(.Mui-disabled)': { color: v('text-primary'), background: v('disclosure-trigger-background-hover') },
-            '&.Mui-selected': { ...text('base-selected'), color: v('disclosure-selected-color') },
+            '&.Mui-selected': { ...text('selected-base'), color: v('disclosure-selected-color') },
             '&.Mui-focusVisible': k.focusRingInset,
             '&.Mui-disabled': { color: v('text-disabled'), opacity: v('disclosure-opacity-disabled') },
           },
@@ -509,7 +509,7 @@ export default {
       MuiAccordionSummary: {
         styleOverrides: {
           root: {
-            ...text('maximize-md'),
+            ...text('title-base'),
             gap: v('space-4'),
             minHeight: 0,
             padding: `${v('space-4')} ${v('space-6')}`,
@@ -523,13 +523,13 @@ export default {
           expandIconWrapper: { color: v('disclosure-icon-color') },
         },
       },
-      MuiAccordionDetails: { styleOverrides: { root: { ...text('base'), padding: `0 ${v('space-6')} ${v('space-4')}`, color: v('disclosure-content-color') } } },
+      MuiAccordionDetails: { styleOverrides: { root: { ...text('body-base'), padding: `0 ${v('space-6')} ${v('space-4')}`, color: v('disclosure-content-color') } } },
 
       // Overlays.
       MuiTooltip: {
         styleOverrides: {
           tooltip: {
-            ...text('condense'),
+            ...text('body-condense'),
             maxWidth: v('tooltip-max-width'),
             padding: `${v('space-1-5')} ${v('space-2-5')}`,
             borderRadius: v('radius-chrome'),
@@ -546,9 +546,9 @@ export default {
           paper: { ...k.modalSurface, width: v('modal-width'), maxWidth: v('modal-max-width'), maxHeight: v('modal-max-height'), margin: v('space-4') },
         },
       },
-      MuiDialogTitle: { styleOverrides: { root: { ...text('maximize-xl'), padding: 0, color: v('modal-title-color') } } },
+      MuiDialogTitle: { styleOverrides: { root: { ...text('title-amplify'), padding: 0, color: v('modal-title-color') } } },
       MuiDialogContent: { styleOverrides: { root: { padding: 0, '.MuiDialogTitle-root + &': { paddingTop: 0 } } } },
-      MuiDialogContentText: { styleOverrides: { root: { ...text('base'), color: v('modal-description-color') } } },
+      MuiDialogContentText: { styleOverrides: { root: { ...text('body-base'), color: v('modal-description-color') } } },
       MuiDialogActions: {
         styleOverrides: { root: { padding: 0, gap: v('modal-actions-gap'), marginTop: v('modal-actions-spacing'), '& > :not(style) ~ :not(style)': { marginLeft: 0 } } },
       },
@@ -557,11 +557,11 @@ export default {
       },
 
       // Feedback.
-      MuiSnackbarContent: { styleOverrides: { root: { ...k.popupSurface, ...text('base'), padding: v('notice-padding') } } },
+      MuiSnackbarContent: { styleOverrides: { root: { ...k.popupSurface, ...text('body-base'), padding: v('notice-padding') } } },
       MuiAlert: {
         styleOverrides: {
           root: {
-            ...text('base'),
+            ...text('body-base'),
             padding: v('notice-padding'),
             gap: v('notice-gap'),
             borderRadius: v('popup-radius'),
@@ -577,7 +577,7 @@ export default {
           },
         },
       },
-      MuiAlertTitle: { styleOverrides: { root: { ...text('maximize-md'), margin: `0 0 ${v('notice-text-gap')}` } } },
+      MuiAlertTitle: { styleOverrides: { root: { ...text('title-base'), margin: `0 0 ${v('notice-text-gap')}` } } },
       MuiLinearProgress: {
         styleOverrides: {
           root: {
@@ -599,7 +599,7 @@ export default {
       MuiAvatar: {
         styleOverrides: {
           root: {
-            ...text('maximize-md'),
+            ...text('title-base'),
             width: v('avatar-size-md'),
             height: v('avatar-size-md'),
             boxSizing: 'border-box',
@@ -613,8 +613,8 @@ export default {
       MuiAvatarGroup: { styleOverrides: { avatar: { border: `${v('stroke-emphasis')} solid ${v('surface-canvas')}`, boxSizing: 'border-box' } } },
       MuiTableCell: {
         styleOverrides: {
-          root: { ...text('condense'), color: v('table-color'), borderBottom: `${v('stroke-default')} solid ${v('table-row-border-color')}`, paddingInline: v('table-cell-padding-inline') },
-          head: { ...text('base-label'), background: v('table-header-background'), color: v('table-header-color') },
+          root: { ...text('body-condense'), color: v('table-color'), borderBottom: `${v('stroke-default')} solid ${v('table-row-border-color')}`, paddingInline: v('table-cell-padding-inline') },
+          head: { ...text('label-base'), background: v('table-header-background'), color: v('table-header-color') },
         },
       },
       MuiTableRow: { styleOverrides: { root: { '&.MuiTableRow-hover:hover': { background: v('table-row-hover') }, '&.Mui-selected, &.Mui-selected:hover': { background: v('table-row-selected') } } } },
@@ -628,7 +628,7 @@ export default {
       typography: {
         fontFamily: theme.fonts.body,
         ...Object.fromEntries(Object.entries(TYPE).map(([variant, style]) => [variant, text(style)])),
-        button: { ...text('base-trigger'), textTransform: 'none' },
+        button: { ...text('trigger-base'), textTransform: 'none' },
       },
       components,
     };

package/exporters/shadcn.mjs

@@ -7,6 +7,7 @@
  * It replaces everything after the imports in shadcn's globals.css. Only colors,
  * the radius, fonts and text sizes follow the brand; shadcn's own spacing and shapes stay.
  */
+import { darkVariant } from './tailwind.mjs';
 
 /** shadcn variable → Loomiere token path. */
 const VARIABLES = {
@@ -48,7 +49,7 @@ const VARIABLES = {
 };
 
 /** shadcn's text sizes → the text tier whose size they take. */
-const SIZES = { xs: 'minimize', sm: 'condense', base: 'base', lg: 'magnify' };
+const SIZES = { xs: 'body-minimize', sm: 'body-condense', base: 'body-base', lg: 'body-magnify' };
 
 export default {
   id: 'shadcn',
@@ -72,8 +73,8 @@ export default {
    @import "<theme>/exports/shadcn.css";
    Replaces everything after the imports in shadcn's globals.css. Every variable
    points at a --${theme.prefix}- concept, so dark mode, contrast modes and color vision themes come
-   along. Dark mode is data-theme="dark" on <html> (next-themes: attribute="data-theme"), or the
-   system setting. With the Loomiere Tailwind theme as well, import this after it: text-xs to
+   along. Dark mode is data-theme="dark" or "dark-high-contrast" on <html> (next-themes:
+   attribute="data-theme"), or the system setting. With the Loomiere Tailwind theme as well, import this after it: text-xs to
    text-lg come back for shadcn's components, sized by the text tiers. */
 @import "../tokens.css";
 
@@ -81,16 +82,7 @@ export default {
 ${root.join('\n')}
 }
 
-@custom-variant dark {
-  &:where([data-theme='dark'], [data-theme='dark'] *) {
-    @slot;
-  }
-  @media (prefers-color-scheme: dark) {
-    &:where(:root:not([data-theme='light']), :root:not([data-theme='light']) *) {
-      @slot;
-    }
-  }
-}
+${darkVariant(theme)}
 
 @theme inline {
 ${[...colors, ...fonts, ...sizes].join('\n')}

package/exporters/tailwind.mjs

@@ -60,7 +60,7 @@ export default {
   id: 'tailwind',
   name: 'Tailwind CSS v4',
   file: 'tailwind.css',
-  for: 'Tailwind v4 projects: import after tailwindcss (it brings tokens.css along). Utilities like bg-accent-solid, text-fg, bg-emphasis-bg, and text styles by tier: text-base, text-magnify-trigger.',
+  for: 'Tailwind v4 projects: import after tailwindcss (it brings tokens.css along). Utilities like bg-accent-solid, text-fg, bg-emphasis-bg, and text styles by tier: text-body-base, text-trigger-magnify.',
   build(theme) {
     const name = new Map(theme.tokens.map((t) => [t.path, t.name]));
     const line = (twVar, path) => (name.has(path) ? `  ${twVar}: var(${name.get(path)});` : null);
@@ -102,7 +102,7 @@ export default {
     for (const g of ['popup', 'modal']) lines.push(line(`--shadow-${g}`, `${g}.shadow`));
     // Media queries can't read custom properties, so breakpoints are written as values.
     const breakpoints = theme.tokens.filter((t) => /^breakpoint\.[\w-]+$/.test(t.path)).map((t) => `  --breakpoint-${t.path.slice(11)}: ${t.value};`);
-    // Each text style is one utility named by its tier (text-base, text-magnify-trigger), so a
+    // Each text style is one utility named by its tier (text-body-base, text-trigger-magnify), so a
     // class sets family, size, weight, line height and letter spacing together.
     const styles = new Map();
     for (const t of theme.tokens) {
@@ -113,9 +113,9 @@ export default {
     // z-index layers by name (z-modal, z-toast); Tailwind's z-10 and friends still work.
     const z = theme.tokens.filter((t) => /^z-index\.[\w-]+$/.test(t.path)).map((t) => `@utility z-${t.path.slice(8)} {\n  z-index: var(${t.name});\n}`);
     const durations = theme.tokens.filter((t) => /^duration\.[\w-]+$/.test(t.path)).map((t) => `@utility duration-${t.path.slice(9)} {\n  --tw-duration: var(${t.name});\n  transition-duration: var(${t.name});\n}`);
-    // dark: follows Loomiere's mode: data-theme="dark" on <html>, or the system setting
-    // unless data-theme="light" says otherwise.
-    const dark = `@custom-variant dark {\n  &:where([data-theme='dark'], [data-theme='dark'] *) {\n    @slot;\n  }\n  @media (prefers-color-scheme: dark) {\n    &:where(:root:not([data-theme='light']), :root:not([data-theme='light']) *) {\n      @slot;\n    }\n  }\n}`;
+    // dark: follows Loomiere's theme: data-theme="dark" or "dark-high-contrast" on <html>, or
+    // the system setting unless data-theme names a light theme (color vision themes are light).
+    const dark = darkVariant(theme);
     // Brand pairs and color scopes as utilities (pair-stone-soft, scope-error), the same
     // declarations as .${theme.prefix}-pair-<name> and [data-color='<name>'] in tokens.css, so
     // variants work on them: md:pair-stone-soft, hover:scope-error.
@@ -137,3 +137,12 @@ export default {
 @theme inline {\n${lines.filter(Boolean).join('\n')}\n}\n\n@theme {\n  --breakpoint-*: initial;\n${breakpoints.join('\n')}\n}\n\n${[dark, ...utilities, ...z, ...durations, ...pairs, ...scopeUtilities].filter(Boolean).join('\n\n')}\n`;
   },
 };
+
+/** Tailwind's dark variant on Loomiere's themes; shadcn.mjs uses it too. */
+export function darkVariant(theme) {
+  const visions = [...new Set(theme.tokens.filter((t) => t.path.startsWith('vision.')).map((t) => t.path.split('.')[1]))];
+  const list = (names) => names.map((n) => `[data-theme='${n}']`).join(', ');
+  const dark = list(['dark', 'dark-high-contrast']);
+  const notLight = `:root:not(${list(['light', 'light-high-contrast', ...visions])})`;
+  return `@custom-variant dark {\n  &:where(${dark}, :is(${dark}) *) {\n    @slot;\n  }\n  @media (prefers-color-scheme: dark) {\n    &:where(${notLight}, ${notLight} *) {\n      @slot;\n    }\n  }\n}`;
+}

package/figma/README.md

@@ -0,0 +1,136 @@
+# Figma
+
+Loomiere sends a built theme into a Figma file as variables, text styles and effect styles. The repo stays the
+source of truth: Figma gets a copy that updates in place, so layers bound to a variable or text
+style stay bound when the theme changes.
+
+There are three ways to send it. All three run the same engine (`engine.js`), so the file ends
+up the same whichever you use.
+
+| Who                                     | Way                                                            | What it needs                                                                     |
+| --------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| You, in a Claude chat about the project | Say "sync Figma"                                               | Claude with the Figma connector                                                   |
+| You, in a terminal                      | `npx loomiere figma push`                                      | Claude Code with a Figma connector, or an Enterprise `FIGMA_TOKEN`, or the plugin |
+| A designer without the repo             | The Loomiere plugin: import `figma.json` or pull it from a URL | Figma desktop                                                                     |
+
+Nothing watches for changes. A push happens when someone asks for one.
+
+## What goes into Figma
+
+`loomiere build` writes `exports/figma.json`. It holds the variables in six collections and
+one text style per text style token.
+
+Hidden collections hold the raw values, with a group for each variant. Published collections are
+what designers pick from and switch. Figma picks each collection's mode on its own, and one
+collection's mode can't choose another's, so a variant that a single switch has to change is a
+group in a hidden collection, and the published collection's modes point at the right group.
+
+| 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.                                                                                                                                               |
+| 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. |
+| Status         | Default, Info, Success, Warning, Error, Neutral                                                           | What each emphasis level is in each status (`bold/bg`, `subtle/fg`…): a brand pair the brand file picked (`roles.status`), or the level's style in the status's palette. As `data-status` in CSS; Neutral is the chrome palette, as `data-color="neutral"` (`palette="neutral"`). No scopes; Emphasis reads it.                                                                                                     |
+| Emphasis       | Bold, Standard, Subtle, Quiet                                                                             | The emphasis parts components paint with (`emphasis/bg`, `emphasis/fg`…), as `data-emphasis`, each pointing at its level in Status.                                                                                                                                                                                                                                                                                 |
+
+So one frame can be Dark, Warning and Subtle at once, the same as the CSS, and an emphasized
+component follows the theme set on the page around it.
+
+Files synced before these names are renamed in place on the next sync (Scheme, Theme for the
+pairs, Color, Pairs, Size base), and Brand's colors move into their theme groups, so layers bound
+to them stay bound. Color Pair and Color Role are retired: a sync with "remove" deletes them.
+
+Every variable has its CSS variable as code syntax (`var(--sl-text-primary)`), the token's
+description, and scopes that keep it to the right pickers (text colors only show for text, radii
+only for corners). Text styles follow the Size and Brand variables for their size and family, and
+their description names the CSS class that matches.
+
+Effect styles hold what a variable can't: elevation/xs to elevation/2xl from the shadow tokens,
+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.
+
+### Plans
+
+Modes per collection depend on the Figma plan: Professional allows 10, Organization 20. The sync
+checks the file's limit each time.
+
+- **Professional and up** get the layout above. If a collection has more modes than the plan
+  allows, the extra modes are left out and the sync says which.
+- **Starter** allows one mode per collection, so it gets a simpler layout instead: Brand, Color Pair,
+  Theme and "Theme dark", with sizes at their desktop value and no color vision modes. Moving
+  the file to a paid plan and syncing again switches it to the full layout; sync with "remove"
+  to delete the old collections.
+
+## 1. In a Claude chat
+
+Ask Claude to sync Figma. Claude runs the same steps as `--via scripts` below with the Figma
+connector:
+
+1. `loomiere build`, then `loomiere figma push --via scripts`, which writes a snapshot script.
+2. Runs the snapshot in the Figma file. It returns the plan's mode limit and a short hash for
+   each group of variables (`Brand:default/color/primary`, `Theme:text`…).
+3. `loomiere figma push --via scripts --since <snapshot>` writes numbered scripts holding only
+   the groups that differ, plus a last one with the text and effect styles and anything to remove.
+4. Runs them in order and reports what changed.
+
+After the first push, a change to one palette sends one or two groups, not the whole theme.
+
+## 2. In a terminal: `loomiere figma push`
+
+```bash
+npx loomiere figma push              # build, then push by the first way that works here
+npx loomiere figma push --dry-run    # report what would change
+npx loomiere figma push --remove     # also delete what the build no longer has
+```
+
+Say which file in `loomiere.config.json`:
+
+```json
+{ "figma": { "file": "https://www.figma.com/design/<key>/<name>" } }
+```
+
+or with `--file <url>`. Then it picks a way, or you pick with `--via`:
+
+| `--via`   | When it's picked         | How it works                                                                                                                                                                                                                               |
+| --------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `api`     | `FIGMA_TOKEN` is set     | Writes variables through Figma's REST API. Only Enterprise plans can write variables this way, and the API can't write text or effect styles, so those still need one of the other ways. The token needs the `file_variables:write` scope. |
+| `claude`  | Claude Code is installed | Hands the push to Claude Code (`claude -p`), which runs the steps from the chat way with its Figma connector. Claude Code needs a Figma connector (`claude mcp add` or the claude.ai Figma connector).                                     |
+| `plugin`  | Neither of the above     | Serves the build at `http://localhost:4322/figma.json` and asks you to click **Pull from project** in the plugin.                                                                                                                          |
+| `scripts` | Only when asked          | Writes the push scripts to `<out>/figma-push/` and stops. What the chat way and `--via claude` run.                                                                                                                                        |
+
+`npx loomiere figma serve` serves the build for the plugin without pushing. `loomiere studio`
+serves it too, at the same address, so a designer next to you can pull while you edit.
+
+## 3. The Loomiere plugin
+
+For designers who don't run the repo. Until it's published to the Figma Community:
+
+1. Get this package (`npm pack @scattered-light/loomiere`, or a clone of the repo).
+2. In the Figma desktop app: **Plugins › Development › Import plugin from manifest…** and pick
+   `figma/plugin/manifest.json`.
+3. Run **Plugins › Development › Loomiere**.
+
+Then bring a theme in one of three ways:
+
+- **Theme file:** drop or choose a `figma.json`. Whoever builds the theme can send it over; it's
+  in `exports/` of every build.
+- **Pull from project:** reads `http://localhost:4322/figma.json` from `loomiere studio` or
+  `loomiere figma serve` on the same computer.
+- **Pull from URL:** a published theme package, for example
+  `https://unpkg.com/@scattered-light/loomiere-mojave/dist/exports/figma.json`.
+
+The plugin checks the file first and lists what it will create, change and remove. Nothing
+changes until you click **Apply**. Leave "Also delete" off to keep anything the theme no longer
+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`.                                                                                                                       |
+| `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/build-plugin.mjs

@@ -0,0 +1,25 @@
+/**
+ * Writes plugin/code.js: the sync engine plus the plugin's own few lines, as the one file a
+ * Figma plugin runs. `node figma/build-plugin.mjs --check` fails if code.js is out of date.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const out = path.join(here, 'plugin', 'code.js');
+const code = [
+  '// Generated by figma/build-plugin.mjs from engine.js and plugin-main.js. Do not edit.',
+  fs.readFileSync(path.join(here, 'engine.js'), 'utf8'),
+  fs.readFileSync(path.join(here, 'plugin-main.js'), 'utf8'),
+].join('\n');
+
+if (process.argv.includes('--check')) {
+  if (!fs.existsSync(out) || fs.readFileSync(out, 'utf8') !== code) {
+    console.error('figma/plugin/code.js is out of date: run npm run build -w @scattered-light/loomiere');
+    process.exitCode = 1;
+  }
+} else {
+  fs.writeFileSync(out, code);
+  console.log(`Wrote ${path.relative(process.cwd(), out)}.`);
+}