figma-plugin-utilities 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-05-06
+
+WCAG 2.2 AA accessibility audit and remediation across all components.
+
+### Added
+- `class` prop passthrough to **ListItem**, **LoadingState**, and **StatusBar** — consistent with other components
+- `role="alert"` for error/warning and `role="status"` for info/success on **StatusBar** — messages are now announced by screen readers on insertion
+- `"AAA-large"` case (4.5:1) to `meetsContrastLevel` in `lib/colors.js` — covers WCAG 1.4.6 large text at AAA level
+- GitHub Actions publish workflow (`.github/workflows/publish.yml`) — triggers `npm publish` on GitHub release creation
+- `aria-pressed={active}` to **ListItem** — communicates selection state to assistive technology
+- Space key activation to **ListItem** — keyboard users can now toggle items with Space as well as Enter
+- `ariaLabel="{title} options"` to the **ListItem** menu `IconButton` — gives the icon-only button an accessible name
+- `role="status"` to **LoadingState** — loading message is announced as a polite live region
+- `aria-hidden="true"` to the decorative icon in **EmptyState** — prevents redundant AT announcement
+- `aria-disabled` attribute to **CheckboxCard** — reflects disabled state without removing from the accessibility tree
+- Dev-mode `console.warn` to **FieldGroup** when `label` is provided but `labelFor` is empty
+
+### Changed
+- **Header**: outer element changed from `<div>` to `<header>`; title changed from `<h2>` to `<h1>` (plugin UI runs in its own iframe, so the heading hierarchy starts fresh)
+- **Footer**: outer element changed from `<div>` to `<footer>`
+- **CheckboxCard**: removed `role="button"` and `tabindex` from the wrapper div — the native checkbox input is the sole interactive/focusable element; the wrapper remains clickable for mouse users via a delegating click handler
+- **CheckboxCard**: added `user-select: none` to prevent text selection on double-click
+
+## [0.1.0] - 2026-04-17
+
+Initial release as `figma-plugin-utilities`.
+
+### Added
+- **PluginLayout** — main content wrapper with scrollable area
+- **Header** — header bar with left/center/right slots and optional title
+- **Footer** — footer bar with right, split, and full layout variants
+- **StatusBar** — toast-style notifications with auto-dismiss for info/success types
+- **EmptyState** — empty/error state display with optional icon and action buttons
+- **ListItem** — selectable list item with metadata slot and context menu
+- **LoadingState** — centered loading indicator
+- **FieldGroup** — label + input wrapper for form fields
+- **CheckboxCard** — large-target checkbox with card styling
+- `lib/messages.js` — `sendToPlugin` and `createMessageHandler`
+- `lib/colors.js` — `rgbToHex`, `hexToRgb`, `getLuminance`, `getContrastRatio`, `meetsContrastLevel`
+- `lib/validation.js` — `validateUrl`, `validateJsonString`, `validateEmail`, `validateNumber`, `sanitizeName`, `sanitizeInput`, `isEmpty`
+- `lib/errorHandling.js` — `safeAsync`, `parseJsonSafe`, `notifyError`, `notifySuccess`, `notifyWarning`, and more
+- `lib/resize.js` — `resizeToFit`, `autoResize`, `setDefaultWidth`, `getContentHeight`
+- `lib/figma-helpers.ts` — `sendToUI`, `showError`, `showSuccess`, `getCollections`, `getVariables`, `getSelection`, `focusNodes`, `loadFont`, `saveToStorage`, `loadFromStorage`, `handleResize`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marius Roosendaal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,11 @@
-# figma-plugin-utils
+# figma-plugin-utilities
 
 Shared Svelte components and utilities for Figma plugins.
 
 ## Installation
 
 ```bash
-npm install figma-plugin-utils
+npm install figma-plugin-utilities
 ```
 
 ## Usage
@@ -23,25 +23,46 @@ import {
   ListItem,
   LoadingState,
   FieldGroup,
-  // Utilities
+  CheckboxCard,
+  // Messages
   sendToPlugin,
   createMessageHandler,
+  // Colors
   rgbToHex,
   hexToRgb,
+  getLuminance,
+  getContrastRatio,
+  meetsContrastLevel,
+  // Validation
   validateUrl,
   validateJsonString,
+  validateEmail,
+  validateNumber,
   sanitizeName,
-} from "figma-plugin-utils";
+  sanitizeInput,
+  isEmpty,
+  // Error handling
+  safeAsync,
+  parseJsonSafe,
+  notifyError,
+  notifySuccess,
+  notifyWarning,
+  // Resize
+  setDefaultWidth,
+  getContentHeight,
+  resizeToFit,
+  autoResize,
+} from "figma-plugin-utilities";
 ```
 
 ### Import Specific Modules
 
 ```javascript
 // Components only
-import { PluginLayout, Header, Footer } from "figma-plugin-utils/components";
+import { PluginLayout, Header, Footer } from "figma-plugin-utilities/components";
 
 // Utilities only
-import { sendToPlugin, createMessageHandler } from "figma-plugin-utils/lib";
+import { sendToPlugin, createMessageHandler } from "figma-plugin-utilities/lib";
 ```
 
 ## Components
@@ -56,6 +77,7 @@ import { sendToPlugin, createMessageHandler } from "figma-plugin-utils/lib";
 | `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 |
 
 ### Header
 
@@ -140,6 +162,37 @@ Types: `info`, `success`, `error`, `warning`. Auto-dismisses after 4s for `info`
 </ListItem>
 ```
 
+### CheckboxCard
+
+Large checkbox with card-style background and better touch targets.
+
+```svelte
+<!-- Basic usage -->
+<CheckboxCard
+  checked={isSelected}
+  on:change={handleToggle}
+>
+  Small
+</CheckboxCard>
+
+<!-- With secondary text -->
+<CheckboxCard
+  checked={isSelected}
+  on:change={handleToggle}
+>
+  Small
+  <svelte:fragment slot="secondary">400px</svelte:fragment>
+</CheckboxCard>
+
+<!-- Disabled state -->
+<CheckboxCard
+  checked={true}
+  disabled={true}
+>
+  Large
+</CheckboxCard>
+```
+
 ## Utilities
 
 ### Messages (`lib/messages.js`)
@@ -162,7 +215,8 @@ window.onmessage = createMessageHandler({
 const rgb = hexToRgb("#FF0000"); // { r: 1, g: 0, b: 0 }
 const hex = rgbToHex({ r: 1, g: 0, b: 0 }); // "#FF0000"
 
-// Calculate contrast
+// Contrast utilities
+const luminance = getLuminance({ r: 1, g: 0, b: 0 });
 const ratio = getContrastRatio(color1, color2);
 const passes = meetsContrastLevel(ratio, "AA"); // true/false
 ```
@@ -176,7 +230,12 @@ const urlResult = validateUrl("https://example.com");
 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
 ```
 
 ### Error Handling (`lib/errorHandling.js`)
@@ -196,20 +255,71 @@ if (result.ok) {
 // Parse JSON safely
 const parsed = parseJsonSafe(jsonString);
 // { ok: true, value: {...} } or { ok: false, error: "..." }
+
+// Figma notifications
+notifySuccess("Done!");
+notifyError("Something went wrong");
+notifyWarning("Check your input");
+```
+
+### Resize (`lib/resize.js`)
+
+Utilities for dynamically resizing the plugin window to fit its content.
+
+```javascript
+// One-time resize to fit content
+resizeToFit({ width: 300, minHeight: 100, maxHeight: 600 });
+
+// Watch for content changes and auto-resize
+const cleanup = autoResize({
+  container: myContainerEl, // bind:this on a naturally-flowing wrapper
+  width: 300,
+  minHeight: 100,
+  maxHeight: 600,
+});
+
+// Call cleanup when the component is destroyed
+onDestroy(cleanup);
+
+// Set default width used across all resize calls
+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.
+
 ### Figma Helpers (`lib/figma-helpers.ts`)
 
 For use in `code.ts`:
 
 ```typescript
-import { sendToUI, showError, focusNodes, loadFont } from "figma-plugin-utils/lib/figma-helpers";
+import {
+  sendToUI,
+  showError,
+  showSuccess,
+  getCollections,
+  getVariables,
+  getSelection,
+  focusNodes,
+  loadFont,
+  saveToStorage,
+  loadFromStorage,
+  handleResize,
+} from "figma-plugin-utilities/lib/figma-helpers";
 
 // Send message to UI
 sendToUI("success", { message: "Done!" });
 
-// Show notification
+// Show notifications
 showError("Something went wrong");
+showSuccess("Created!");
+
+// Variables
+const collections = await getCollections();
+const colorVars = await getVariables("COLOR");
+
+// Selection
+const selected = getSelection(); // all selected nodes
+const frames = getSelection("FRAME"); // filtered by type
 
 // Focus viewport on nodes
 focusNodes(figma.currentPage.selection);
@@ -220,4 +330,7 @@ await loadFont("Inter", "Regular");
 // Client storage
 await saveToStorage("settings", { theme: "dark" });
 const settings = await loadFromStorage("settings", { theme: "light" });
+
+// Handle resize message from UI (call in your message handler)
+if (msg.type === "resize") handleResize(msg);
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-plugin-utilities",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Shared Svelte components and utilities for Figma plugins",
   "type": "module",
   "svelte": "./src/index.js",
@@ -21,13 +21,21 @@
       "import": "./src/lib/index.js",
       "default": "./src/lib/index.js"
     },
+    "./lib/*": {
+      "import": "./src/lib/*.js"
+    },
     "./lib/figma-helpers": {
       "types": "./src/lib/figma-helpers.ts",
       "import": "./src/lib/figma-helpers.ts",
       "default": "./src/lib/figma-helpers.ts"
     }
   },
-  "files": ["src"],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mariusroosendaal/figma-plugin-utilities.git"
@@ -47,7 +55,7 @@
   "author": "Marius Roosendaal",
   "license": "MIT",
   "dependencies": {
-    "figma-ui3-kit-svelte": "^0.4.0",
+    "figma-ui3-kit-svelte": "^0.5.0",
     "svelte": "^4.2.20"
   }
 }

package/src/components/CheckboxCard.svelte

@@ -0,0 +1,108 @@
+<script>
+  import { createEventDispatcher } from "svelte";
+  import { Checkbox } from "figma-ui3-kit-svelte";
+
+  /**
+   * Large checkbox card component with better touch targets
+   * Wraps the standard checkbox in a card-like layout
+   *
+   * @example
+   * <CheckboxCard
+   *   checked={isSelected}
+   *   on:change={handleToggle}
+   * >
+   *   Small
+   * </CheckboxCard>
+   *
+   * @example with secondary text
+   * <CheckboxCard
+   *   checked={isSelected}
+   *   on:change={handleToggle}
+   * >
+   *   Small
+   *   <svelte:fragment slot="secondary">400px</svelte:fragment>
+   * </CheckboxCard>
+   */
+
+  const dispatch = createEventDispatcher();
+
+  /** Whether checkbox is checked */
+  export let checked = false;
+
+  /** Whether checkbox is disabled */
+  export let disabled = false;
+
+  let cardEl;
+
+  function handleChange(e) {
+    if (disabled) return;
+    checked = e.target.checked;
+    dispatch("change", { checked });
+  }
+
+  function handleCardClick(e) {
+    if (disabled) return;
+    // Clicks inside the Checkbox component (label/input) are handled natively
+    if (e.target.closest(".checkbox-container")) return;
+    cardEl?.querySelector('input[type="checkbox"]')?.click();
+  }
+</script>
+
+<!-- svelte-ignore a11y-click-events-have-key-events a11y-no-static-element-interactions -->
+<!-- Keyboard users interact with the native checkbox input inside; this div is a mouse-only larger click target -->
+<div
+  class="checkbox-card"
+  class:disabled
+  aria-disabled={disabled || undefined}
+  bind:this={cardEl}
+  on:click={handleCardClick}
+>
+  <Checkbox {checked} {disabled} on:change={handleChange}>
+    <slot />
+  </Checkbox>
+  {#if $$slots.secondary}
+    <div class="checkbox-card__secondary">
+      <slot name="secondary" />
+    </div>
+  {/if}
+</div>
+
+<style>
+  .checkbox-card {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0 var(--size-xxxsmall);
+    background: var(--figma-color-bg-secondary);
+    border: 1px solid transparent;
+    border-radius: var(--border-radius-medium);
+    cursor: pointer;
+    min-height: 24px;
+    user-select: none;
+  }
+
+  .checkbox-card:hover {
+    border-color: var(--figma-color-border);
+    background: var(--figma-color-bg-secondary);
+  }
+
+  .checkbox-card.disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  /* Custom checkbox styling for card variant */
+  .checkbox-card :global(.checkbox-box) {
+    background-color: var(--figma-color-bg);
+  }
+
+  .checkbox-card__secondary {
+    font-size: var(--body-small-font-size);
+    font-weight: var(--body-small-font-weight);
+    letter-spacing: var(--body-small-letter-spacing);
+    line-height: var(--body-small-line-height);
+    color: var(--figma-color-text-secondary);
+    margin-left: auto;
+    padding-left: var(--size-xsmall);
+  }
+</style>

package/src/components/EmptyState.svelte

@@ -30,18 +30,20 @@
   /** Whether to center vertically */
   export let centered = true;
 
+  let className = '';
+  export { className as class };
   // Normalize actions
   $: normalizedActions = actions ? actions : action ? [action] : null;
 </script>
 
 <div
-  class="empty-state"
+  class="empty-state {className}"
   class:centered
   class:small={size === "small"}
   class:large={size === "large"}
 >
   {#if icon}
-    <div class="empty-state__icon">
+    <div class="empty-state__icon" aria-hidden="true">
       {#if typeof icon === "string"}
         <Icon iconName={icon} />
       {:else}

package/src/components/FieldGroup.svelte

@@ -16,11 +16,18 @@
 
   /** For attribute for the label (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">
+<div class="field-group" class:small={size === "small"}>
   {#if label}
-    <Label for={labelFor}>{label}</Label>
+    <Label for={labelFor} {size}>{label}</Label>
   {/if}
   <slot />
 </div>
@@ -31,4 +38,8 @@
     flex-direction: column;
     gap: var(--size-xxsmall);
   }
+
+  .field-group.small {
+    gap: var(--size-xxxsmall);
+  }
 </style>

package/src/components/Footer.svelte

@@ -31,7 +31,7 @@
   export let className = "";
 </script>
 
-<div class="footer footer--{variant} {className}">
+<footer class="footer footer--{variant} {className}">
   {#if variant === "right"}
     <div class="footer__right">
       <slot />
@@ -46,7 +46,7 @@
   {:else if variant === "full"}
     <slot />
   {/if}
-</div>
+</footer>
 
 <style>
   .footer {

package/src/components/Header.svelte

@@ -11,7 +11,7 @@
   export let noBorder = false;
 </script>
 
-<div
+<header
   class="header {className}"
   class:has-left-content={$$slots.left}
   class:no-border={noBorder}
@@ -19,7 +19,7 @@
   <div class="header__left">
     <slot name="left" />
     {#if title}
-      <h2 class="header__title">{title}</h2>
+      <h1 class="header__title">{title}</h1>
     {/if}
   </div>
   <div class="header__center">
@@ -28,7 +28,7 @@
   <div class="header__right">
     <slot name="right" />
   </div>
-</div>
+</header>
 
 <style>
   .header {

package/src/components/ListItem.svelte

@@ -44,6 +44,9 @@
   /** Whether to show badge slot */
   export let hasBadge = false;
 
+  let className = "";
+  export { className as class };
+
   function handleClick() {
     dispatch("click", { id });
   }
@@ -65,14 +68,15 @@
   }
 </script>
 
-<div class="list-item-wrapper">
+<div class="list-item-wrapper {className}">
   <div
     class="list-item"
     class:active
     on:click={handleClick}
-    on:keydown={(e) => e.key === "Enter" && handleClick()}
+    on:keydown={(e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); handleClick(); } }}
     role="button"
     tabindex="0"
+    aria-pressed={active}
   >
     <div class="list-item__content">
       <div class="list-item__title">{title}</div>
@@ -92,6 +96,7 @@
   {#if menuItems.length > 0}
     <IconButton
       iconName={IconMore}
+      ariaLabel="{title} options"
       bind:element={menuButtonElement}
       on:click={handleMenuToggle}
     />

package/src/components/LoadingState.svelte

@@ -15,9 +15,12 @@
 
   /** Message to display */
   export let message = "Loading...";
+
+  let className = "";
+  export { className as class };
 </script>
 
-<div class="loading-state">
+<div class="loading-state {className}" role="status">
   <Text variant="body-medium" color="--figma-color-text-secondary">{message}</Text>
 </div>
 

package/src/components/PluginLayout.svelte

@@ -6,9 +6,7 @@
    * @example
    * <PluginLayout>
    *   <p>Main content here</p>
-   *   <svelte:fragment slot="footer">
-   *     <Button variant="primary">Create item</Button>
-   *   </svelte:fragment>
+   *   <Button variant="primary">Create item</Button>
    * </PluginLayout>
    */
 
@@ -40,4 +38,8 @@
     overflow-y: auto;
     padding: var(--size-xsmall);
   }
+
+  .plugin-footer {
+    flex-shrink: 0;
+  }
 </style>

package/src/components/StatusBar.svelte

@@ -14,6 +14,9 @@
   /** Status type: 'info', 'success', 'error', 'warning' */
   export let type = "info";
 
+  let className = "";
+  export { className as class };
+
   let visible = false;
   let timeoutId;
 
@@ -53,14 +56,16 @@
 
 {#if visible && message}
   <div
-    class="status-bar"
+    class="status-bar {className}"
     class:status-bar--error={type === "error"}
     class:status-bar--success={type === "success"}
     class:status-bar--warning={type === "warning"}
+    role={type === "error" || type === "warning" ? "alert" : "status"}
   >
     <span>{message}</span>
     <IconButton
       iconName={IconClose}
+      ariaLabel="Dismiss"
       on:click={handleClose}
       iconColor={computedIconColor}
     />

package/src/components/index.js

@@ -1,4 +1,5 @@
 // Svelte components
+export { default as CheckboxCard } from "./CheckboxCard.svelte";
 export { default as EmptyState } from "./EmptyState.svelte";
 export { default as FieldGroup } from "./FieldGroup.svelte";
 export { default as Footer } from "./Footer.svelte";

package/src/index.js

@@ -1,5 +1,6 @@
 // Re-export all components
 export {
+  CheckboxCard,
   EmptyState,
   FieldGroup,
   Footer,
@@ -37,6 +38,9 @@ export {
   withErrorHandling,
   safeAsync,
   parseJsonSafe,
+  notifyError,
+  notifySuccess,
+  notifyWarning,
   // Resize
   setDefaultWidth,
   getContentHeight,

package/src/lib/colors.js

@@ -60,13 +60,15 @@ export function getContrastRatio(color1, color2) {
 /**
  * Check if contrast ratio meets WCAG level
  * @param {number} ratio - Contrast ratio
- * @param {"AA" | "AAA" | "AA-large"} level - WCAG level to check
+ * @param {"AA" | "AAA" | "AA-large" | "AAA-large"} level - WCAG level to check
  * @returns {boolean} Whether the ratio meets the level
  */
 export function meetsContrastLevel(ratio, level) {
   switch (level) {
     case "AAA":
       return ratio >= 7;
+    case "AAA-large":
+      return ratio >= 4.5;
     case "AA":
       return ratio >= 4.5;
     case "AA-large":

package/src/lib/resize.js

@@ -2,12 +2,12 @@
  * Auto-resize utilities for Figma plugin windows
  *
  * Usage in UI:
- *   import { resizeToFit, autoResize } from "figma-plugin-utils";
+ *   import { resizeToFit, autoResize } from "figma-plugin-utilities";
  *   resizeToFit(); // One-time resize
  *   autoResize();  // Watch for changes and auto-resize
  *
  * Usage in code.ts:
- *   import { handleResize } from "figma-plugin-utils/lib/figma-helpers";
+ *   import { handleResize } from "figma-plugin-utilities/lib/figma-helpers";
  *   // In your message handler:
  *   if (msg.type === "resize") handleResize(msg);
  */