figma-plugin-utilities 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,11 +1,29 @@
 # 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
 

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.1",
+  "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": [
@@ -55,20 +60,20 @@
   "author": "Marius Roosendaal",
   "license": "MIT",
   "devDependencies": {
-    "@eslint/js": "^9.39.1",
-    "@figma/plugin-typings": "^1.51.0",
+    "@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.1",
-    "eslint-plugin-svelte": "^2.46.0",
-    "figma-ui3-kit-svelte": "file:..//_packages/figma-ui3-kit-svelte",
-    "globals": "^16.5.0",
-    "prettier": "3.7.3",
+    "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": "^0.39.0",
+    "svelte-eslint-parser": "^1.8.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.48.0",
+    "typescript-eslint": "^8.70.0",
     "vite": "^5.2.0"
   },
   "scripts": {

package/src/components/EmptyState.svelte

@@ -62,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/StatusBar.svelte

@@ -1,4 +1,9 @@
 <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 } from "figma-ui3-kit-svelte";
   import { IconClose } from "figma-ui3-kit-svelte/icons";
@@ -43,7 +48,6 @@
   } else {
     visible = false;
   }
-
   function handleClose() {
     visible = false;
     clearTimeout(timeoutId);
@@ -82,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/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>;
+}