figma-plugin-utilities 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,11 +1,39 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+## [Unreleased]
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.4.0] - 2026-09-21
 
-## [Unreleased]
+### Added
+- `figma-frame-builders.ts` — new module with Figma frame and component builder utilities, imported from `figma-plugin-utilities/lib/figma-frame-builders` (its own export entry). They mirror the Vitrine spec library — colours, typography, spacing and layer names (`label` chip and text, a `tokens` row in token cells, `title` in both header variants):
+  - `createAutoLayoutFrame` — creates a `FrameNode` with auto-layout configured
+  - `createAutoLayoutComponent` — creates a `ComponentNode` with auto-layout configured
+  - `createText` — creates a styled `TextNode`
+  - `createTokenChip` — creates a rounded chip frame for displaying color tokens
+  - `createColorSwatch` — creates a color swatch frame
+  - `createTableCell` — creates a table cell frame
+  - `createTableHeader` — creates a table header frame
+  - `loadSpecFonts` — loads Inter and IBM Plex Mono font faces in parallel
+  - `specTokens` — design token constants (accent colors, font specs, light/dark themes with an optional `headerBorder`)
+  - `PaddingSpec`, `SpecTheme`, `NodeKind` and `NodeFor` types
+
+### Removed
+- The dev-mode `console.warn` **FieldGroup** logged when `label` was set without `labelFor` — a `Dropdown` is a button and cannot be a `<label for>` target, so it fired on correct code. Dropped in the a11y pass, recorded late
+
+### Fixed
+- **StatusBar** — the default `info` type sets `color: var(--figma-color-text)`. The `error`, `success` and `warning` types each set a foreground; the default one relied on inheritance, and nothing up the tree sets `color`, so the message rendered in the UA's black on the dark theme's grey bar
+- **EmptyState** — the actions are a keyed `{#each}`, so swapping one action for another reuses the right button rather than repainting the row
+- **docs** — `figma-frame-builders` is documented, `sanitizeInput` no longer claims to escape HTML (it stringifies, truncates, strips control characters and trims), and `formatErrorMessage`, `handleAsyncError`, `withErrorHandling` and `logError` are documented with their real signatures. `withErrorHandling(fn, operation)` calls `fn()` with no arguments and returns its result; it was documented as returning a wrapped function
+
+## [0.3.1] - 2026-05-13
+
+### Added
+- ESLint configuration with TypeScript and Svelte support for code linting
+- Prettier setup with Svelte plugin for consistent code formatting
+- `lint` and `prettier` npm scripts for development workflow
+
+### Changed
+- Updated **ListItem** and **StatusBar** to use icon imports from `figma-ui3-kit-svelte/icons` after the UI kit icon export restructure.
 
 ## [0.3.0] - 2026-05-06
 

package/README.md

@@ -73,11 +73,13 @@ import { sendToPlugin, createMessageHandler } from "figma-plugin-utilities/lib";
 | `Header` | Header bar with `left`, `center`, `right` slots and optional title |
 | `Footer` | Footer with `right`, `split`, and `full` layout variants |
 | `StatusBar` | Toast notifications with auto-dismiss (info/success/error/warning) |
-| `EmptyState` | Empty/error states with optional icon and action buttons |
-| `ListItem` | Selectable list items with metadata slot and action menu |
-| `LoadingState` | Centered loading indicator with custom message |
-| `FieldGroup` | Label + input wrapper for form fields |
-| `CheckboxCard` | Large checkbox with card styling and better touch targets |
+| `EmptyState` | Empty/error states with optional icon and action buttons; `size`, `centered`, and `role="alert"` for failures |
+| `ListItem` | Selectable list items with metadata and `badge` slots, an action menu (`menuOpen`, `menuToggle`, `menuClose`) |
+| `LoadingState` | Centred message as `role="status"` (text only, no spinner) |
+| `FieldGroup` | Label + input wrapper; `labelFor` binds the label to a text control |
+| `CheckboxCard` | Large checkbox with card styling and better touch targets; `change` event |
+
+Every component also takes a `class` (or `className`) prop.
 
 ### Header
 
@@ -231,11 +233,14 @@ const jsonResult = validateJsonString('{"key": "value"}');
 // { valid: true, parsed: {...} } or { valid: false, error: "..." }
 
 validateEmail("user@example.com"); // { valid: true }
-validateNumber("42", { min: 0, max: 100 }); // { valid: true, value: 42 }
-
-const clean = sanitizeName("My Plugin!!!"); // "My Plugin"
-sanitizeInput("<script>alert(1)</script>"); // escaped string
-isEmpty(""); // true
+validateNumber("42", { min: 0, max: 100, integer: true }); // { valid: true, value: 42 }
+validateUrl("", { required: false }); // { valid: true } — empty is allowed
+validateJsonString(text, { maxSizeKB: 512, requireObject: true });
+
+const clean = sanitizeName("My Plugin!!!", 200); // "My Plugin" — "Untitled" if nothing survives
+sanitizeInput(input, 50); // stringify, truncate to maxLength, strip control characters, trim
+// Note: sanitizeInput does NOT escape HTML. Escape at the point of rendering instead.
+isEmpty(""); // true — also for [] and {}
 ```
 
 ### Error Handling (`lib/errorHandling.js`)
@@ -287,6 +292,26 @@ setDefaultWidth(320);
 
 > **Note:** The `container` element passed to `autoResize` must **not** have `height: 100%` or a fixed height — it should flow naturally with its content so `scrollHeight` can be measured accurately.
 
+### Spec Frame Builders (`lib/figma-frame-builders.ts`)
+
+Typed builders for canvas frames in a spec or documentation generator — auto-layout frames and components, text, token chips, colour swatches, table cells and headers, with light and dark palettes.
+
+```typescript
+import {
+  specTokens, loadSpecFonts,
+  createAutoLayoutFrame, createAutoLayoutComponent, createText,
+  createTokenChip, createColorSwatch, createTableCell, createTableHeader,
+} from "figma-plugin-utilities/lib/figma-frame-builders";
+
+await loadSpecFonts(); // once, before drawing
+const theme = specTokens.themes.dark;
+
+const row = createAutoLayoutFrame({ name: "row", direction: "HORIZONTAL", spacing: 8, fill: theme.cellFill });
+row.appendChild(createTokenChip({ label: "#FFFFFF", background: theme.chipBg, textColor: theme.text }));
+```
+
+`specTokens` carries `accentColors`, `fonts` and `themes` (`light`, `dark`). Builders that can return either node take `as: "component"` for a `ComponentNode` instead of a `FrameNode`. Exported types: `PaddingSpec`, `SpecTheme`, `NodeKind`, `NodeFor`.
+
 ### Figma Helpers (`lib/figma-helpers.ts`)
 
 For use in `code.ts`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-plugin-utilities",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared Svelte components and utilities for Figma plugins",
   "type": "module",
   "svelte": "./src/index.js",
@@ -28,6 +28,11 @@
       "types": "./src/lib/figma-helpers.ts",
       "import": "./src/lib/figma-helpers.ts",
       "default": "./src/lib/figma-helpers.ts"
+    },
+    "./lib/figma-frame-builders": {
+      "types": "./src/lib/figma-frame-builders.ts",
+      "import": "./src/lib/figma-frame-builders.ts",
+      "default": "./src/lib/figma-frame-builders.ts"
     }
   },
   "files": [
@@ -54,8 +59,25 @@
   ],
   "author": "Marius Roosendaal",
   "license": "MIT",
-  "dependencies": {
-    "figma-ui3-kit-svelte": "^0.5.0",
-    "svelte": "^4.2.20"
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@figma/plugin-typings": "^1.138.0",
+    "@sveltejs/vite-plugin-svelte": "^3.0.2",
+    "@types/node": "^22.13.4",
+    "eslint": "^9.39.2",
+    "eslint-plugin-svelte": "^3.23.0",
+    "figma-ui3-kit-svelte": "^0.6.0",
+    "globals": "^17.12.0",
+    "prettier": "^3.9.8",
+    "prettier-plugin-svelte": "^3.4.0",
+    "svelte": "^4.2.20",
+    "svelte-eslint-parser": "^1.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.70.0",
+    "vite": "^5.2.0"
+  },
+  "scripts": {
+    "lint": "tsc --noEmit && eslint . --ext .ts,.js,.svelte && npx prettier --check \"src/**/*.{js,ts,svelte,html,css}\"",
+    "prettier": "npx prettier --write \"src/**/*.{js,ts,svelte,html,css}\""
   }
 }

package/src/components/EmptyState.svelte

@@ -30,9 +30,12 @@
   /** Whether to center vertically */
   export let centered = true;
 
-  let className = '';
+  /** ARIA role: "status" for info messages, "alert" for errors */
+  export let role = "status";
+
+  let className = "";
   export { className as class };
-  // Normalize actions
+
   $: normalizedActions = actions ? actions : action ? [action] : null;
 </script>
 
@@ -41,6 +44,7 @@
   class:centered
   class:small={size === "small"}
   class:large={size === "large"}
+  {role}
 >
   {#if icon}
     <div class="empty-state__icon" aria-hidden="true">
@@ -58,7 +62,7 @@
 
   {#if normalizedActions && normalizedActions.length > 0}
     <div class="empty-state__actions">
-      {#each normalizedActions as actionItem}
+      {#each normalizedActions as actionItem (actionItem.label)}
         <Button variant="secondary" on:click={actionItem.handler}>
           {actionItem.label}
         </Button>

package/src/components/FieldGroup.svelte

@@ -1,28 +1,14 @@
 <script>
   import { Label } from "figma-ui3-kit-svelte";
 
-  /**
-   * Field group wrapper
-   * Wraps a form field with an optional label
-   *
-   * @example
-   * <FieldGroup label="Collection">
-   *   <Dropdown menuItems={options} bind:value={selected} />
-   * </FieldGroup>
-   */
-
   /** Label text (optional) */
   export let label = "";
 
-  /** For attribute for the label (optional) */
+  /** id of the associated control (optional) */
   export let labelFor = "";
 
   /** Size of the label (optional) */
   export let size = undefined;
-
-  $: if (typeof window !== "undefined" && label && !labelFor) {
-    console.warn("[FieldGroup] A label is rendered but no labelFor is set. Associate the label with its control using the labelFor prop.");
-  }
 </script>
 
 <div class="field-group" class:small={size === "small"}>

package/src/components/Footer.svelte

@@ -103,6 +103,10 @@
     width: 100%;
   }
 
+  .footer--full :global(> *) {
+    flex: 1;
+  }
+
   .footer--full :global(button) {
     flex: 1;
     width: 100%;

package/src/components/ListItem.svelte

@@ -1,6 +1,7 @@
 <script>
   import { createEventDispatcher } from "svelte";
-  import { IconButton, IconMore, Menu } from "figma-ui3-kit-svelte";
+  import { IconButton, Menu } from "figma-ui3-kit-svelte";
+  import { IconMore } from "figma-ui3-kit-svelte/icons";
 
   /**
    * List item with optional action menu
@@ -73,7 +74,12 @@
     class="list-item"
     class:active
     on:click={handleClick}
-    on:keydown={(e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); handleClick(); } }}
+    on:keydown={(e) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        handleClick();
+      }
+    }}
     role="button"
     tabindex="0"
     aria-pressed={active}

package/src/components/LoadingState.svelte

@@ -21,7 +21,9 @@
 </script>
 
 <div class="loading-state {className}" role="status">
-  <Text variant="body-medium" color="--figma-color-text-secondary">{message}</Text>
+  <Text variant="body-medium" color="--figma-color-text-secondary"
+    >{message}</Text
+  >
 </div>
 
 <style>

package/src/components/StatusBar.svelte

@@ -1,6 +1,12 @@
 <script>
+  /* The auto-dismiss below trips svelte/infinite-reactive-loop: the reactive
+     statement writes `visible`, and the timeout it schedules writes it again
+     through handleClose(). Neither reads `visible`, so the statement cannot
+     re-trigger itself — the rule only sees the shared assignment target. */
+  /* eslint-disable svelte/infinite-reactive-loop */
   import { onDestroy, createEventDispatcher } from "svelte";
-  import { IconButton, IconClose } from "figma-ui3-kit-svelte";
+  import { IconButton } from "figma-ui3-kit-svelte";
+  import { IconClose } from "figma-ui3-kit-svelte/icons";
 
   // Status bar for notifications with auto-dismiss
   // Supports types: 'info', 'success', 'error', 'warning'
@@ -42,7 +48,6 @@
   } else {
     visible = false;
   }
-
   function handleClose() {
     visible = false;
     clearTimeout(timeoutId);
@@ -81,6 +86,7 @@
     align-items: center;
     justify-content: space-between;
     background: var(--figma-color-bg-secondary);
+    color: var(--figma-color-text);
     font-size: var(--body-medium-font-size);
     font-weight: var(--body-medium-font-weight);
     letter-spacing: var(--body-medium-letter-spacing);

package/src/lib/colors.js

@@ -39,7 +39,8 @@ export function hexToRgb(hex) {
  * @returns {number} Relative luminance (0-1)
  */
 export function getLuminance({ r, g, b }) {
-  const adjust = (c) => (c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+  const adjust = (c) =>
+    c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
   return 0.2126 * adjust(r) + 0.7152 * adjust(g) + 0.0722 * adjust(b);
 }
 

package/src/lib/figma-frame-builders.ts

@@ -0,0 +1,467 @@
+export type PaddingSpec =
+  number | { top?: number; right?: number; bottom?: number; left?: number };
+
+export type SpecTheme = {
+  cellFill: RGB;
+  cellBorder: RGB;
+  text: RGB;
+  chipBg: RGB;
+  headerFill: RGB;
+  subheaderFill: RGB;
+  headingText: RGB;
+  /** Bottom rule under the header; the inverse header has none. */
+  headerBorder?: RGB;
+};
+
+export type NodeKind = "frame" | "component";
+export type NodeFor<K extends NodeKind> = K extends "component"
+  ? ComponentNode
+  : FrameNode;
+
+function rgb(r: number, g: number, b: number): RGB {
+  return { r, g, b };
+}
+
+function createNode<K extends NodeKind>(as?: K): NodeFor<K> {
+  return (
+    as === "component" ? figma.createComponent() : figma.createFrame()
+  ) as NodeFor<K>;
+}
+
+function applyPadding(
+  frame: FrameNode | ComponentNode,
+  spec: PaddingSpec,
+): void {
+  if (typeof spec === "number") {
+    frame.paddingTop = spec;
+    frame.paddingRight = spec;
+    frame.paddingBottom = spec;
+    frame.paddingLeft = spec;
+  } else {
+    frame.paddingTop = spec.top ?? 0;
+    frame.paddingRight = spec.right ?? 0;
+    frame.paddingBottom = spec.bottom ?? 0;
+    frame.paddingLeft = spec.left ?? 0;
+  }
+}
+
+export const specTokens = {
+  accentColors: {
+    green: rgb(0.337, 0.757, 0.396), // #56C165 — AAA
+    blue: rgb(0.447, 0.682, 0.988), // #72AEFC — AA
+    purple: rgb(0.753, 0.608, 0.965), // #C09BF6 — AA18
+    red: rgb(0.98, 0.553, 0.569), // #FA8D91 — DNP
+  },
+  fonts: {
+    body: { family: "Inter", style: "Regular", size: 14 },
+    bodyBold: { family: "Inter", style: "Semi Bold", size: 14 },
+    subheading: { family: "Inter", style: "Medium", size: 24 },
+    heading: { family: "Inter", style: "Medium", size: 48 },
+    code: { family: "IBM Plex Mono", style: "Regular", size: 12 },
+  },
+  themes: {
+    light: {
+      cellFill: rgb(1.0, 1.0, 1.0), // #FFFFFF
+      cellBorder: rgb(0.949, 0.949, 0.949), // #F2F2F2
+      text: rgb(0.09, 0.09, 0.09), // #171717
+      chipBg: rgb(0.949, 0.949, 0.949), // #F2F2F2
+      headerFill: rgb(1.0, 1.0, 1.0), // #FFFFFF
+      subheaderFill: rgb(0.949, 0.949, 0.949), // #F2F2F2
+      headingText: rgb(0.09, 0.09, 0.09), // #171717
+      headerBorder: rgb(0.886, 0.886, 0.886), // #E2E2E2
+    } satisfies SpecTheme,
+    dark: {
+      cellFill: rgb(0.09, 0.09, 0.09), // #171717
+      cellBorder: rgb(0.114, 0.114, 0.114), // #1D1D1D
+      text: rgb(1.0, 1.0, 1.0), // #FFFFFF
+      chipBg: rgb(0.157, 0.157, 0.157), // #282828
+      headerFill: rgb(0.09, 0.09, 0.09), // #171717
+      subheaderFill: rgb(0.157, 0.157, 0.157), // #282828
+      headingText: rgb(1.0, 1.0, 1.0), // #FFFFFF
+    } satisfies SpecTheme,
+  },
+};
+
+export async function loadSpecFonts(): Promise<void> {
+  await Promise.all([
+    figma.loadFontAsync({ family: "Inter", style: "Regular" }),
+    figma.loadFontAsync({ family: "Inter", style: "Semi Bold" }),
+    figma.loadFontAsync({ family: "Inter", style: "Medium" }),
+    figma.loadFontAsync({ family: "IBM Plex Mono", style: "Regular" }),
+  ]);
+}
+
+type AutoLayoutOpts = {
+  name: string;
+  direction: "HORIZONTAL" | "VERTICAL" | "NONE";
+  spacing?: number;
+  padding?: PaddingSpec;
+  fill?: RGB;
+  cornerRadius?: number;
+  width?: number;
+  height?: number;
+  clipsContent?: boolean;
+  border?: { color: RGB; width?: number };
+};
+
+function applyAutoLayout(
+  node: FrameNode | ComponentNode,
+  opts: AutoLayoutOpts,
+): void {
+  node.name = opts.name;
+  node.layoutMode = opts.direction;
+  node.fills = opts.fill ? [{ type: "SOLID", color: opts.fill }] : [];
+
+  if (opts.cornerRadius !== undefined) node.cornerRadius = opts.cornerRadius;
+  if (opts.clipsContent !== undefined) node.clipsContent = opts.clipsContent;
+  if (opts.padding !== undefined) applyPadding(node, opts.padding);
+
+  if (opts.direction !== "NONE") {
+    node.itemSpacing = opts.spacing ?? 0;
+    const isHorizontal = opts.direction === "HORIZONTAL";
+    node.primaryAxisSizingMode =
+      (isHorizontal ? opts.width : opts.height) !== undefined
+        ? "FIXED"
+        : "AUTO";
+    node.counterAxisSizingMode =
+      (isHorizontal ? opts.height : opts.width) !== undefined
+        ? "FIXED"
+        : "AUTO";
+  }
+
+  if (opts.width !== undefined || opts.height !== undefined) {
+    node.resize(opts.width ?? node.width, opts.height ?? node.height);
+  }
+
+  if (opts.border) {
+    node.strokes = [{ type: "SOLID", color: opts.border.color }];
+    node.strokeWeight = opts.border.width ?? 1;
+    node.strokeAlign = "CENTER";
+  }
+}
+
+export function createAutoLayoutFrame(opts: AutoLayoutOpts): FrameNode {
+  const frame = figma.createFrame();
+  applyAutoLayout(frame, opts);
+  return frame;
+}
+
+export function createAutoLayoutComponent(opts: AutoLayoutOpts): ComponentNode {
+  const component = figma.createComponent();
+  applyAutoLayout(component, opts);
+  return component;
+}
+
+export function createText(opts: {
+  characters: string;
+  font: { family: string; style: string; size: number };
+  color?: RGB;
+  lineHeight?: number;
+  letterSpacing?: number;
+  width?: number;
+}): TextNode {
+  const node = figma.createText();
+  node.fontName = { family: opts.font.family, style: opts.font.style };
+  node.fontSize = opts.font.size;
+
+  if (opts.lineHeight !== undefined) {
+    node.lineHeight = { value: opts.lineHeight * 100, unit: "PERCENT" };
+  }
+  if (opts.letterSpacing !== undefined) {
+    node.letterSpacing = { value: opts.letterSpacing, unit: "PIXELS" };
+  }
+
+  node.characters = opts.characters;
+  node.fills = [
+    { type: "SOLID", color: opts.color ?? specTokens.themes.light.text },
+  ];
+
+  if (opts.width !== undefined) {
+    node.textAutoResize = "HEIGHT";
+    node.resize(opts.width, node.height);
+  }
+
+  return node;
+}
+
+export function createTokenChip<K extends NodeKind = "frame">(opts: {
+  label: string;
+  background: RGB;
+  textColor?: RGB;
+  width?: number;
+  as?: K;
+}): NodeFor<K> {
+  const node = createNode(opts.as);
+  applyAutoLayout(node, {
+    name: "label",
+    direction: "VERTICAL",
+    padding: { right: 4, left: 4 },
+    fill: opts.background,
+    cornerRadius: 2,
+    height: 24,
+    width: opts.width,
+  });
+  node.primaryAxisAlignItems = "CENTER";
+  const text = createText({
+    characters: opts.label,
+    font: specTokens.fonts.code,
+    color: opts.textColor ?? specTokens.themes.light.text,
+    lineHeight: 1.4,
+    letterSpacing: 0.18,
+  });
+  text.name = "label";
+  text.textAutoResize = "WIDTH_AND_HEIGHT";
+  node.appendChild(text);
+  return node as NodeFor<K>;
+}
+
+export function createColorSwatch<K extends NodeKind = "frame">(opts: {
+  color: RGB;
+  size?: number;
+  cornerRadius?: number;
+  inverse?: boolean;
+  as?: K;
+}): NodeFor<K> {
+  const size = opts.size ?? 40;
+  const node = createNode(opts.as);
+  applyAutoLayout(node, {
+    name: "swatch",
+    direction: "NONE",
+    fill: opts.color,
+    cornerRadius: opts.cornerRadius ?? 2,
+    width: size,
+    height: size,
+  });
+  node.strokes = [
+    {
+      type: "SOLID",
+      color: opts.inverse ? rgb(1, 1, 1) : rgb(0, 0, 0),
+      opacity: 0.1,
+    },
+  ];
+  node.strokeWeight = 1;
+  node.strokeAlign = "INSIDE";
+  return node as NodeFor<K>;
+}
+
+function chipOrInstance(
+  source: ComponentNode | undefined,
+  label: string,
+  background: RGB,
+  textColor: RGB,
+): FrameNode | InstanceNode {
+  if (source) return source.createInstance();
+  return createTokenChip({ label, background, textColor });
+}
+
+// The library cell holds its chips in a "tokens" slot, a hugging row.
+function tokensRow(chip: FrameNode | InstanceNode): FrameNode {
+  const row = createAutoLayoutFrame({
+    name: "tokens",
+    direction: "HORIZONTAL",
+    spacing: 4,
+  });
+  row.appendChild(chip);
+  return row;
+}
+
+function swatchOrInstance(
+  source: ComponentNode | undefined,
+  color: RGB,
+  inverse: boolean,
+): FrameNode | InstanceNode {
+  if (source) return source.createInstance();
+  return createColorSwatch({ color, inverse });
+}
+
+export function createTableCell<K extends NodeKind = "frame">(opts: {
+  variant: "text" | "header" | "token";
+  theme?: SpecTheme;
+  swatch?: boolean;
+  text?: string;
+  chipLabel?: string;
+  chipBackground?: RGB;
+  swatchColor?: RGB;
+  chipSource?: ComponentNode;
+  swatchSource?: ComponentNode;
+  width?: number;
+  height?: number;
+  textSizing?: "fill" | "hug";
+  as?: K;
+}): NodeFor<K> {
+  const theme = opts.theme ?? specTokens.themes.light;
+  const border = { color: theme.cellBorder };
+  const isTokenSwatch = opts.variant === "token" && opts.swatch;
+
+  if (isTokenSwatch) {
+    const node = createNode(opts.as);
+    applyAutoLayout(node, {
+      name: "table-cell",
+      direction: "HORIZONTAL",
+      padding: { top: 12, right: 20, bottom: 12, left: 20 },
+      fill: theme.cellFill,
+      width: opts.width ?? 240,
+      height: opts.height ?? 72,
+      border,
+    });
+    node.primaryAxisAlignItems = "SPACE_BETWEEN";
+    node.counterAxisAlignItems = "MIN";
+    node.appendChild(
+      tokensRow(
+        chipOrInstance(
+          opts.chipSource,
+          opts.chipLabel ?? "",
+          opts.chipBackground ?? theme.chipBg,
+          theme.text,
+        ),
+      ),
+    );
+    node.appendChild(
+      swatchOrInstance(
+        opts.swatchSource,
+        opts.swatchColor ?? rgb(0, 0, 0),
+        theme.cellFill.r < 0.5,
+      ),
+    );
+    return node as NodeFor<K>;
+  }
+
+  const isTextSwatch = opts.variant === "text" && opts.swatch;
+  const defaultHeight = isTextSwatch ? 72 : 56;
+
+  const node = createNode(opts.as);
+  applyAutoLayout(node, {
+    name: "table-cell",
+    direction: "HORIZONTAL",
+    spacing: opts.variant === "token" ? 8 : isTextSwatch ? 16 : 0,
+    padding: { top: 12, right: 20, bottom: 16, left: 20 },
+    fill: theme.cellFill,
+    width: opts.width ?? 240,
+    height: opts.height ?? defaultHeight,
+    border,
+  });
+
+  if (isTextSwatch) {
+    node.primaryAxisAlignItems = "SPACE_BETWEEN";
+    node.counterAxisAlignItems = "MIN";
+    const label = createText({
+      characters: opts.text ?? "",
+      font: specTokens.fonts.body,
+      color: theme.text,
+      lineHeight: 1.4,
+      width: 144,
+    });
+    label.name = "text";
+    node.appendChild(label);
+    node.appendChild(
+      swatchOrInstance(
+        opts.swatchSource,
+        opts.swatchColor ?? rgb(0, 0, 0),
+        theme.cellFill.r < 0.5,
+      ),
+    );
+    return node as NodeFor<K>;
+  }
+
+  if (opts.variant === "token") {
+    node.appendChild(
+      tokensRow(
+        chipOrInstance(
+          opts.chipSource,
+          opts.chipLabel ?? "",
+          opts.chipBackground ?? theme.chipBg,
+          theme.text,
+        ),
+      ),
+    );
+    return node as NodeFor<K>;
+  }
+
+  // "text" and "header" variants
+  const isBold = opts.variant === "header";
+  const label = createText({
+    characters: opts.text ?? "",
+    font: isBold ? specTokens.fonts.bodyBold : specTokens.fonts.body,
+    color: theme.text,
+    lineHeight: 1.4,
+  });
+  label.name = "text";
+  if (opts.textSizing === "hug") {
+    label.textAutoResize = "WIDTH_AND_HEIGHT";
+  } else {
+    label.layoutGrow = 1;
+    label.textAutoResize = "HEIGHT";
+  }
+  node.appendChild(label);
+
+  return node as NodeFor<K>;
+}
+
+export function createTableHeader<K extends NodeKind = "frame">(opts: {
+  variant: "header" | "subheader";
+  theme?: SpecTheme;
+  title?: string;
+  width?: number;
+  height?: number;
+  as?: K;
+}): NodeFor<K> {
+  const theme = opts.theme ?? specTokens.themes.light;
+  const title = opts.title ?? "";
+
+  if (opts.variant === "header") {
+    const node = createNode(opts.as);
+    applyAutoLayout(node, {
+      name: "table-header",
+      direction: "VERTICAL",
+      padding: { top: 16, right: 20, bottom: 16, left: 20 },
+      width: opts.width ?? 960,
+      height: opts.height ?? 160,
+      fill: theme.headerFill,
+    });
+    if (theme.headerBorder) {
+      node.strokes = [{ type: "SOLID", color: theme.headerBorder }];
+      node.strokeTopWeight = 0;
+      node.strokeRightWeight = 0;
+      node.strokeBottomWeight = 1;
+      node.strokeLeftWeight = 0;
+      node.strokeAlign = "INSIDE";
+    }
+    const text = createText({
+      characters: title,
+      font: specTokens.fonts.heading,
+      color: theme.headingText,
+      lineHeight: 1,
+      letterSpacing: -1.92,
+    });
+    text.name = "title";
+    node.appendChild(text);
+    text.layoutSizingHorizontal = "FILL";
+    text.textAutoResize = "HEIGHT";
+    return node as NodeFor<K>;
+  }
+
+  // subheader: the title sits on the bottom edge
+  const node = createNode(opts.as);
+  applyAutoLayout(node, {
+    name: "table-subheader",
+    direction: "VERTICAL",
+    spacing: 8,
+    padding: { top: 16, right: 20, bottom: 16, left: 20 },
+    fill: theme.subheaderFill,
+    width: opts.width ?? 960,
+    height: opts.height ?? 96,
+  });
+  node.primaryAxisAlignItems = "MAX";
+  const text = createText({
+    characters: title,
+    font: specTokens.fonts.subheading,
+    color: theme.headingText,
+    lineHeight: 1.3,
+    letterSpacing: -0.48,
+  });
+  text.name = "title";
+  node.appendChild(text);
+  text.layoutSizingHorizontal = "FILL";
+  text.textAutoResize = "HEIGHT";
+  return node as NodeFor<K>;
+}

package/src/lib/figma-helpers.ts

@@ -9,7 +9,7 @@
  */
 export function sendToUI<T extends Record<string, unknown>>(
   type: string,
-  data?: T
+  data?: T,
 ): void {
   if (data) {
     figma.ui.postMessage({ type, ...data });
@@ -32,7 +32,7 @@ export async function getCollections(): Promise<VariableCollection[]> {
  * @returns Promise resolving to array of variables
  */
 export async function getVariables(
-  type?: VariableResolvedDataType
+  type?: VariableResolvedDataType,
 ): Promise<Variable[]> {
   return figma.variables.getLocalVariablesAsync(type);
 }
@@ -61,7 +61,7 @@ export function showSuccess(message: string, timeout = 3000): void {
  * @returns Array of selected nodes
  */
 export function getSelection<T extends SceneNode>(
-  nodeType?: NodeType
+  nodeType?: NodeType,
 ): readonly T[] {
   const selection = figma.currentPage.selection;
   if (nodeType) {
@@ -85,10 +85,7 @@ export function focusNodes(nodes: readonly SceneNode[]): void {
  * @param family - Font family name
  * @param style - Font style (e.g., "Regular", "Bold")
  */
-export async function loadFont(
-  family: string,
-  style: string
-): Promise<void> {
+export async function loadFont(family: string, style: string): Promise<void> {
   await figma.loadFontAsync({ family, style });
 }
 
@@ -109,7 +106,7 @@ export async function saveToStorage<T>(key: string, value: T): Promise<void> {
  */
 export async function loadFromStorage<T>(
   key: string,
-  defaultValue?: T
+  defaultValue?: T,
 ): Promise<T | undefined> {
   try {
     const value = await figma.clientStorage.getAsync(key);

package/src/lib/index.js

@@ -1,8 +1,5 @@
 // Message utilities
-export {
-  sendToPlugin,
-  createMessageHandler,
-} from "./messages.js";
+export { sendToPlugin, createMessageHandler } from "./messages.js";
 
 // Color utilities
 export {

package/src/lib/resize.js

@@ -73,10 +73,10 @@ export function resizeToFit(options = {}) {
 /**
  * Set up automatic resizing when content changes
  * Uses ResizeObserver to watch for size changes
- * 
+ *
  * IMPORTANT: The container element must NOT have height: 100% or fixed height.
  * Use bind:this on a wrapper element that flows naturally with content.
- * 
+ *
  * @param {object} options - Auto-resize options
  * @param {HTMLElement} options.container - Container element to observe (required, must not have fixed height)
  * @param {number} [options.width] - Width in pixels (uses default if not specified)

package/src/lib/validation.js

@@ -58,7 +58,7 @@ export function validateUrl(url, options = { required: true }) {
     }
 
     return { valid: true };
-  } catch (err) {
+  } catch {
     return {
       valid: false,
       error: "Invalid URL format",
@@ -148,6 +148,7 @@ export function sanitizeInput(input, maxLength) {
   }
 
   // Remove null bytes and control characters (except newlines and tabs)
+  // eslint-disable-next-line no-control-regex
   str = str.replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F]/g, "");
 
   // Trim whitespace