Storage

Systema uses two storage layers with different scoping:

figma.root.pluginData -- per-file, shared across all users

Key	Contents
systema_config	Full theme configuration (all themes as JSON)
systema_layout	UI layout state: scroll positions, window size, active tabs, display/AI settings, disabled agents
systema_pushed	{ themeId, themeName, pushedAt, schemaHash } of the theme currently represented by this file's Systema variables. Written after every successful push, read on startup to mark the active theme in the UI and on push to detect cross-theme overwrites

Any user who opens the file sees the same config and layout. Last save wins.

figma.clientStorage -- per-user, private, cross-file

Key	Contents
systema_chat_v3_{fileKey}_{themeId}	Chat history for a specific theme (LZ-string compressed JSON). Per-user, per-file, per-theme
systema_api_key_{provider}	API keys for anthropic, openai, openrouter, gemini
systema_user_settings	Settings-dialog values, grouped Display + Helpers + AI (info-panel toggles, hotkey hints, footer panels, contrast cheatsheet, UI theme, border mode, preview direction/verbosity, vision scope; autosave on/off + interval, transitions on/off + duration; AI model/temperature, current agent, AI panel mode, agent edit policy, debate limit, conversational mode, auto-name, auto-collapse). Follows the user across every Figma file. (The AI provider and per-agent overrides are not persisted here — they reset on reload and only survive via the Settings export file below.)

figma.clientStorage is provided by the Plugin API and lives on the client (desktop or web), independent of how the iframe UI is loaded — it works in both the Figma desktop app and the web app at figma.com. Each user has their own chat history, API keys, and Settings-dialog values; nothing here is shared with collaborators on the same file. Storage is local to the client, so it does not sync between different browsers or between desktop and web on the same account. File-level layout state (zoom, scroll positions, sectionStates, selected theme, …) stays in pluginData so it lives with the file.

systema_user_settings lives in figma.clientStorage rather than browser localStorage — localStorage is unavailable when Figma loads the UI from a data: URL (browsers disable Storage in data: contexts), whereas clientStorage persists reliably in every Figma client.

Variable collection tags (pluginData on collections)

Key	Contents
systema_managed = "true"	Marks the collection (or a preview scene-node) as Systema-created. Only things with this tag are swept on replace-theme or cleared by Danger Zone actions
systema_theme = {themeId}	Links the collection to a specific theme id. Under the single-theme-in-Figma policy there's only one active id in the file, but the tag is still written — used for OOM-safe filtering during index and as a fallback "which theme lives here" lookup when systema_pushed is empty
systema_hash	FNV-1a hash of the collection's tokens (paths + per-mode values) from the last push. Used for fast-skip when re-pushing an unchanged collection

Per-variable plugin data:

Key	Contents
systema_tid = {stable-semantic-id}	Computed by buildTid([...pathParts]) in the token engine. Survives path renames and collection-structure switches, letting the push flow find an existing variable by meaning instead of by name

Settings export/import

Settings can be exported as a single systema-settings.json file and imported on another file or machine via the Settings dialog header buttons. The exported blob is { version: 1, display, helpers, ai, apiKeys } — Display toggles, Helpers (autosave / transitions), the AI config + per-agent overrides, and the stored API keys. (This is separate from theme JSON export, which lives in the Theme Settings dialog and carries the design tokens.)

---