figcraft/docs/components-parity.md

Components, variants, styles and variables parity

Last reviewed: 2026-10-10 · Last updated: 2026-10-30 · Change: minor (a collection of this file can be extended (Extend collection on its row, variable.extendCollection), its extension following its edits at once, and extended collections extend again in the file; a typed or stored variable, collection or mode id names only the object with that id (#1613); colour variables can be calculated from other colours per mode — {alpha} replaces a colour's alpha, {mix} blends two — and follow them (#1280); stored variable and collection references keep their identity when another object is named like their id (follow-up to #1542); a component set's property rows fit the 240 px right panel: variant values wrap two to a line there and every + and − stays in view; opening a file contacts no team library server it names until you check it (#1097); an explicit variables file path (variable.import, the variables of file.open and file.import) is refused past 256 MiB or when it isn't a regular file, as the sibling variables.json already was (part of #1114); component properties keep the order they were made in when one is renamed, and Make slot asks for the slot's name first (#1536, #1537); components can't contain their own instances, directly or through others (#1084); the instance-swap menus have a search field (#1338); an instance-swap property's default menu scrolls (#1338); variables on a text style's fields from the style editor; instance-swap properties in the component playground; duplicating or Alt-dragging a main component makes an instance of it (#892); a bound colour variable's alpha applies once (#802); variables import reads variables outside meta and warns when it imports none (#790); variant properties reorder by drag; library files saved right after a read are read again; Hide when publishing note corrected; size and resizing overrides of layers inside instances (#731); variables export in the browser as a download; core editor leftovers: component playground, variables inside styles; layers and assets panels behaviour suite and fixes; extended collections tail; styles and variables behaviour suite and fixes; components behaviour suite and fixes; team libraries on the server, library usage and swapping a library; extended collections, variables import/export, gradient stops and variant properties bound to variables) · Target: Figma Design (desktop app 126.10.7)

Design systems are why teams adopt Figma. Components: breadth ~96%, ready ~72%. Styles and variables: breadth ~95%, ready ~76% (estimated). QA'd with a synthetic design system of ~300 components used 2,000 times (crates/engine/src/content/synthetic_ds.rs, components_scale_tests.rs); not with real libraries. Remaining: 4–10 h here, plus team libraries' tail (4–8 h, partly after accounts).

Components and variants

Feature	Status	Notes
Create component, instances, detach, reset, go to main, restore main, push changes	done	push from a nested layer goes to the outer main
Per-layer overrides with reset; kept across main edits, nested swaps, copy/paste	done	main edits match a full rebuild exactly at 2,000 instances
What an instance overrides: fills, strokes, effects, visibility, layer names, text content and every text property (resizing included), auto layout padding, gap and alignment, layout grids, export settings, prototype interactions, nested swaps and property values; the size and resizing (hug, fill, fixed, min and max) of layers inside it	done	each kept when the main changes that property, reset per group; opacity and corner radius too (documentation silent); size and resizing are kept through relayout, undo, save, .fig and REST import and detach, and stay with the instance on push
What it doesn't: position, rotation, constraints and absolute or grid placement of layers inside it, its auto layout direction and other settings, its structure	done	refused with a message, the fields greyed out; the instance itself resizes and its layers follow the main's constraints
Component sets / variants, add variant, switch	done	Combine as variants is in the Object menu, and the canvas and layers context menu and the Design panel offer it when two or more main components are selected; Add variant on a main component not in a set yet makes it a set of itself and the new variant, one undo step (#903); components that are variants already aren't combined again (it used to put a set inside a set)
A main's copy within its file is an instance of it: Duplicate, Alt-drag, Copy then Paste	done	a variant duplicated in its set stays a new variant and a whole set copies as a new set; only the copied roots become instances (a main inside a copied frame is copied as a main); Cut then Paste and pastes into other files keep the component (#892)
A component can't contain its own instance, directly or through other components	done	refused with the loop named (creating, placing, swapping, switching variants, moving, pasting, an instance-swap value); each variant counts as its own component, so a variant may hold a sibling variant's instance unless that one leads back to it; a dropped instance lands on the page; a file holding a loop opens with one instance detached and a note, any other file unchanged; a loop merged in a live session stops expanding where an instance would show itself again (#1084)
Switching variants keeps overrides where names match and both variants had the same value; text layers keep theirs	done
Default variant: the top-left one (new instances, Assets thumbnail, generated code)	done
Variant property order (names rewritten), duplicate combinations reported	done	drag a property in the Properties section to reorder it, one undo step (#679), or component.editProperty {index}
Properties: boolean, text, instance swap (preferred values), variant	done	listed in the order they were made, a rename keeping the place (#1536; the shared ones don't reorder by drag yet); every component menu scrolls past 320 pt, the default of an instance-swap property's too (#1338); the instance-swap menus (an instance's property and swap menus, a property's default, the playground) open with a search field that filters by name as you type, with Up, Down and Enter to pick and Escape to clear then close; the slot and preferred components menus have no search yet
Slots (preferred components, fill menu, kept across updates)	done	Figma 2025 feature; Make slot asks for the name first (a field under the frame's Slot row), and slots are renamed in the component's Properties list (#1537); no rename with only the slot's frame selected yet
Exposed nested instances	done	hidden ones hide their properties
Descriptions	done
Instance swap: panel, Alt-drop from Assets	done	the panel keeps overrides on same-named layers, an Alt-drop from Assets only text layers'
Assets panel: folders by page, frame and slash names (fold away), thumbnails, search, drag into frames and auto layout slots	done	virtualized; component.list gives each one's folder
Hidden from publishing: a leading . or _ in the name	done	the name decides both ways (adding the prefix takes a published component out, removing it brings it back); Hide when publishing in the Assets panel's context menu and Libraries ▸ Hide when publishing (see ui-parity)
Instances pasted into other files follow their mains	done	missing main restorable
Component playground (try properties without placing)	partial	variant, boolean, text and instance-swap properties in the Inspect tab (the swap menu lists the preferred components first, then every component in the file, as in the Design panel) and component.playground; slots have no control there yet
Real-world libraries QA	not checked	gaps #3

The behaviour of instances, overrides, variants and swaps is checked against the public documentation by crates/engine/src/components_behaviour_tests.rs (one table row per documented rule, with its derivation). Where the documentation is silent, the suite pins today's behaviour: layer opacity and corner radius are overridable; rotation of a layer inside an instance is refused with its position; boolean and text property values stay across variants; a missing combination picks the variant matching the most values; reset all keeps the instance's size; an instance's own min / max width and height stay its own. An instance's own export settings and interactions are its own (the main's later changes to them don't reach existing instances, so connections people added are never lost). Nested instance overrides: nested_override_tests.rs; accepting library updates with overrides kept: library_tests.rs, components_scale_tests.rs.

Libraries

Feature	Status	Notes
Publish a file's components, sets, styles and variables (per-asset versions)	done	as local library files
Enable a library in a file; read-only linked copies	done
Library updates available; overrides kept	done	a library file saved again within two seconds of being read, at the same length, is read again (its time stamp can't prove it unchanged; #652)
Team libraries: publish to a figcraft-server under the file, enable by a share link (a view link reads it), background update checks	done	server.md; no team-wide library list or accounts (gaps #10)
Library analytics	partial	instances per component and the files using them, and the instances each file detached (per component and per file), as apps report them; nothing over time, no insertion counts
Swap library (instances, styles and variables to another library's of the same names, overrides kept)	done	what has no match stays and is listed; one undo step

Styles and variables

Feature	Status	Notes
Paint, text, effect, grid styles; style picker; text styles on character ranges	done	behaviour suite: styles_behaviour_tests.rs
Editing a style updates its layers; detach and delete keep values; editing a styled property unlinks that style	done	an edited fill/stroke/effect/grid list or text chars unlink; applying a style replaces variables bound to what it sets; text styles on text layers only
Organising styles: folders by / names, order, duplicate, rename folder, Local styles list	done	style.move (into a folder renames), style.duplicate (right below), style.renameFolder; the page's Local styles list by type and folder (drag to reorder, right-click)
Variables inside styles (paint, effect, grid and text styles; each user resolves them in its own modes)	done	style.bind, style_vars_tests; the editor binds paint colours, shadow colours, blur radii, grid sizes and a text style's font, font style, size, line height and letter spacing, the rest through the command
Variables: colour, number, string, boolean; collections, modes, aliases, scopes, groups	done	behaviour suite: variables_behaviour_tests.rs; aliases same type, no loops (also on create); colour calculations per mode ({alpha}: a colour variable with its alpha replaced, {mix}: a per-channel blend of two colour variables or literals; they compose, can't loop, and bound layers, modes and undo follow them; REST, CSS, Penpot and .fig exports write the colour they show in each of their collection's modes, other collections in their default modes; read-only in the panel, which can swap one for an alias or detach it; variables_colour_tests.rs), beyond the incumbent, whose variables only alias; scopes filter pickers only
Modes: add, duplicate, rename, delete, set as default / reorder	done	layers on Auto follow a new default; explicit modes stay
Deleting a bound variable or its collection	done	layers keep their last value and are unbound; aliases to it take its values and colour calculations reading it keep the colour they show
Code syntax per platform (Web, iOS, Android, Flutter)	done	generated CSS uses the Web name; in the variables JSON; SwiftUI/Compose/ArkUI/Flutter code doesn't name variables yet
Bindings: fills, strokes, effects, opacity, padding, gaps, sizes, radius, font family/style, font size/weight, line height, letter spacing, paragraph spacing/indent, text, visibility, layout grids, instance properties	done	type-checked per field; number variables fill text content; the Design panel's font family and font style menus start with Apply variable (string variables), and a bound one shows its variable in place of the menu; a colour variable bound to a solid paint brings its whole colour, alpha included, once (the paint's opacity restarts at 100% on binding, an opacity set while bound multiplies on top; unbinding moves the alpha back into the opacity)
Explicit modes per frame, library collections' modes	done	stored variable and collection references resolve by exact id in export, library copies and swaps, imported aliases, alias deletion and cycle checks, Dev Inspect, the library mode picker and prototype playback; a collection or variable named like another's id no longer stands in for it there
Gradient stops and variant properties bound to variables	done	a stop's binding follows it when earlier stops are removed
Extended collections	done	this file's collections (Extend collection on a collection's row; following its edits at once, chains included) and library collections, including a library's own extended collections (chains through libraries); overrides per mode with reset; follow library updates, variables new to the library collection being an update of their own; modes inherited. Checked with synthetic libraries only (gaps #14)
Variables import/export (JSON)	done	the REST local variables shape (round-trips; merges by collection, mode and variable name; variableCollections and variables read under meta or at the top level, a warning when no variables are found or fewer than the collections list); CSS custom properties and Dart constants (Flutter) export; a variables file named by path must be a regular file of at most 256 MiB; in the browser the export arrives as a download (import there still needs a file picker)
Expressions in prototype set-variable actions	done	see prototyping-parity

Revision history

Date	Change	Summary
2026-10-30	minor	M3, gap 14: a collection of this file can be extended, as the help center shows (right-click a collection, Extend collection); before, only a library's could. variable.extendCollection {collection, name?} makes " (extended)" with its modes and one inheriting variable per variable, and the Variables editor's collection menu offers it beside Rename and Delete collection. Edits of the collection it extends reach it at once (values in modes it doesn't override, new variables and modes, renames, mode order), so normalising keeps extensions in step whenever variables change, not only on library updates; undo takes both back. An extended collection extends again (parents settle first; an extension doesn't take its parent's overrides as its own), and a loop of extensions from a hostile file comes apart into plain collections keeping their values. Deleting the parent leaves a plain collection with the values it showed, as for libraries. Tests: extended_chain_tests (engine), variables_rename_tests::a_collection_of_this_file_extends_from_its_context_menu (headless UI). Grade unchanged
2026-10-30	minor	Library analytics count detaches: a file that detaches an instance of a library component counts it (kept with the file) and its app reports the counts to the library's server beside its usage; Show usage and library.usage list them per component and per file (detached, detachesKnown). Older servers and apps are unaffected: the reports are new messages and the old ones keep their encoding. Still nothing over time. Numbers unchanged
2026-10-30	minor	M3, #1613: a variable, collection or mode named like another one's id no longer takes its place where an id is stored or typed (expressions, prototype mode switches, font family variables, the panels' labels); names still work where a person types them. Grade unchanged.
2026-10-30	minor	M3, #1280: a colour variable can be calculated from others, per mode: {"alpha": {"variable", "opacity"}} is that variable's colour with its alpha replaced (replace, not multiply, so re-editing the source's alpha never compounds), {"mix": {"from", "to", "t"}} blends two operands ({"variable"} or {"literal"}) per channel over the stored values in the document's colour profile, alpha included (converting the profile keeps a mix's ends exact and moves its colours in between slightly). Calculations resolve lazily like aliases, so bound layers, mode switches, instances and undo follow their sources; they compose (a calculation of a calculation), a loop is refused when it is set, and one resolve consults at most 32 variables. Files keep them; REST, CSS, Penpot and .fig exports write the colour they show in each of their collection's modes (other collections in their default modes, so a CSS calculation doesn't follow another collection's data- mode); deleting a source leaves its readers on the colour they showed; library import and swap re-point their operands. The panel shows them read-only (swatch and formula) and can swap one for an alias or detach it to its colour. Tests: engine/src/variables_colour_tests.rs, doc/src/tests.rs. Left: editing calculations in the panel; files using them need this build to open. Numbers unchanged
2026-10-30	minor	M3, follow-up to #1542: stored variable and collection references use exact ids in export, library copies and swaps, imported aliases, alias deletion and cycle checks, Dev Inspect, the library mode picker, and prototype actions and expressions. Interaction edits resolve only incoming names and leave stored references alone. Command arguments still accept names as before. Tests: the stored_variable_ids_* tests in the doc, engine, format and ui-egui present and responsive suites. Numbers unchanged
2026-10-30	minor	M8: the component set's Properties section fits the narrowest right panel: variant values wrap onto more lines and every + and − button stays visible. Grade unchanged.
2026-10-30	minor	M8, #1097: library updates from a team library a file names are offered, not fetched from its server by themselves: only team libraries you added or checked are checked in the background (Check for updates in Assets ▸ Libraries). Numbers unchanged.
2026-10-30	minor	M8, #1114: variables import from an explicit file path (variable.import, the variables of file.open and file.import) takes regular files of at most 256 MiB, the limit the sibling variables.json already had; anything else is refused before the document changes. Grade unchanged. Tests: import_export_tests::an_explicit_variables_path_is_capped_like_the_sibling_file, variables_io_tests::variables_import_caps_the_file_it_reads
2026-10-30	minor	M3, #1536 and #1537: component properties are listed in the order they were made in, and renaming one keeps its place (they were sorted by name, so a rename moved the property); that holds for every kind, on every variant of a set and on instances, in component.properties, the Design panel and .fig export. Files from before keep their properties by name until one is added or renamed. Make slot (the Slot menu of a frame inside a component) asks for the slot's name first: a field under the Slot row with the frame's name selected, Enter or Make slot to make it, Escape to cancel; a name taken keeps the field open. Renaming stays in the component's Properties list. Tests: engine/src/prop_order_tests.rs, ui-egui/src/make_slot_naming_tests.rs. Left: dragging the shared properties to reorder them, and renaming a slot with only its frame selected. Numbers unchanged
2026-10-29	minor	M3, #1338: the instance-swap property's menu (on an instance, its main component's default and the component playground) and the instance's swap menu open with a search field at the top that has the keyboard; typing filters the components by name (any case, headings without matches drop out), an empty result reads "No matching components", Up and Down step through the matches and Enter picks one (the first without a step), Escape clears the search and then closes the menu. Only the list scrolls; the menu grows back when the search is cleared. Tests: component_swap_search_tests. Numbers unchanged
2026-10-26	minor	An instance-swap property's default menu scrolls (#1338): on the main component's Properties row the menu listed every component in the file at full height, so in a file with many (an icon library) the bottom ones ran off the screen and couldn't be picked. It now scrolls past 320 pt like the instance's swap menu, is at least 200 pt wide, ticks the current default and is named for assistive technology (component_swap_default_tests). Left: searching these menus. Numbers unchanged.
2026-10-24	minor	Variables on a text style's fields from the style editor: the font and font style menus start with Apply variable (string variables), and the size, line height and letter spacing fields show a variable button on hover (number variables). A bound field shows its variable in place of the value; a click on it picks another variable and its detach button unbinds it (style_picker_tests). Left: the other effect and grid fields (commands only), library variables in the picker. Numbers unchanged.
2026-10-23	minor	Instance-swap properties in the component playground: the Inspect tab's Playground shows a dropdown for each, with the same menu as the Design panel's (the property's preferred components first, then every component in the file). The component picked changes the preview and the code only, never the file. Left: slots in the playground. Numbers unchanged.
2026-10-20	minor	A main component's copy within its file is an instance of it (#892): Duplicate (edit.duplicate) and Alt-drag on the canvas made a second main; they now place an instance where the copy went (same offset, the instance's default name, selected), as Copy then Paste already did. A variant duplicated in its set stays a new variant.
2026-10-18	minor	A bound colour variable's alpha applies once (#802): a #RRGGBBAA paint keeps its alpha in the paint opacity, and binding a variable with alpha left that opacity in place, so a 50% fill bound to a 50% variable drew at 25%. Binding (variable.bind, node.set boundVariables, style.bind) now restarts the paint's opacity at 100% and unbinding (also deleting the variable) moves the colour's alpha back into the opacity; .fig and REST imports take the variable's alpha back out of a bound paint's opacity, so .fig round trips no longer square it. Colour-picker edits of a colour variable or a plugin colour field, generated CSS strokes and the document colours list counted the paint opacity twice and now count it once (bound_alpha_tests). Numbers unchanged
2026-10-18	minor	Variables import (#790): a variables map outside meta (or meta.variables next to top-level collections) is read, and an import that finds no variables, or fewer than the collections' variableIds list, says so in warnings instead of succeeding silently
2026-10-17	minor	Variant properties reorder by dragging them in the Properties section, one undo step (#679; was "no drag in the panel yet"); a library file saved again right after it was read is read again, so a quick republish isn't missed (#652); the Hidden from publishing row no longer says the Hide when publishing item is missing (it landed 2026-10-12). Numbers unchanged
2026-10-17	minor	Size and resizing overrides of layers inside instances (#731): a layer in an instance can hug, fill or keep a size of its own (group resizing: hug/fill/fixed with min and max; size), from the Layout panel, the canvas handles and node.set; they were refused, and imported ones were dropped at the first relayout. Kept through main edits of other properties, rebuilds, undo, save, .fig and REST import (sizes a .fig instance gives its layers and the REST overrides fields), .fig export and detach; reset per group and with Reset all changes (instance_resizing_tests). The row that listed them as not overridable was wrong. Numbers unchanged.
2026-10-14	minor	Variables export in the browser: Export… ▸ Variables JSON / CSS custom properties did nothing in the web build, which has no save dialogs; it now hands the file over as a download (Services::downloads / download, variables_export_ui_tests). Import in the browser still needs a file picker, as do the other exports there. Numbers unchanged.
2026-10-13	minor	Component playground (M3): with an instance, a component or a component set selected, the Inspect tab shows a Playground: a preview of the component and a control for each variant, boolean and text property. What is tried there changes the preview and the code in the Code section, never the file (no undo step, the canvas instance stays as it is); Reset goes back to the component's or the instance's own values. component.playground {id?, properties?, language?, path?} gives the same to scripts: the properties with their values, the code, and a PNG on request (playground_tests). Left: instance-swap and slot properties in the playground (the command takes an instance swap; the panel has no control for it), a code connect template's snippet with the tried values. Numbers unchanged.
2026-10-13	minor	Variables inside styles (M3): a shared style can bind variables to fields of its value (style.bind {style, field, variable?}: a paint style's colours and gradient stops, an effect style's colour, radius, spread and offsets, a grid style's size, count, gutter and offset, a text style's font size, line height, letter spacing, family and style). Every layer using the style shows those fields resolved in its own modes and stays linked when a variable or a mode changes; the style keeps them resolved in the default modes. A style made from a layer keeps that layer's bindings; a new value drops bindings to what is gone. The style editor binds from its property rows (paint colour, shadow colour, blur radius, grid size) and detaches from the variable's chip; the style picker marks styles that use variables. .fig export and import carry the bindings on the style, REST layers hand theirs to the style they use. Left: binding text style fields and the other effect and grid fields from the editor (commands only), library variables in the picker, a style's library copy. Numbers unchanged.
2026-10-12	minor	Layers and Assets panels behaviour suite: Assets folders by page, frame and slash names; a leading . or _ keeps a component out of the library even after it was published, and removing it brings the component back
2026-10-12	minor	Extended collections' tail (gap 14): variables a library adds to a collection this file extends now count as a library update of their own (listed by name without a copy yet) and arrive inheriting when accepted, instead of waiting for the library's next other update; a library collection that is itself an extended collection can be extended again, values flowing down the chain as each file accepts updates with every level's overrides kept (checked end to end). Styles & variables breadth 94% → 95%, ready unchanged (76%), 3–5 h → 2–4 h; gap 14 1–2 h → 0–1 h (real-library checks left); feature breadth (~82%) and ready for real work (~51%) unchanged at this rounding; full parity ~305–594 h → ~304–593 h
2026-10-11	minor	Styles and variables behaviour suite from the public documentation (18 tests) and its fixes (styled properties edited away unlink, deleted variables unbind with values kept, type-checked bindings, alias checks on create, text styles on text only); style folders, order and duplicates with a Local styles list; mode duplicate and default; code syntax. Found missing: variables inside styles. Styles and variables breadth ~92% → ~94%, ready ~72% → ~76%; remaining here 7–14 h → 9–17 h
2026-10-11	minor	Behaviour suite from the public documentation and its fixes: overrides of padding, gap, alignment, layout grids, export settings, interactions and every text property kept (they were lost when the main changed); geometry, constraints and resizing of layers inside instances refused; variant switches keep only overrides both variants agreed on (text layers keep theirs); Alt-drops from Assets keep only text overrides; top-left default variant; hidden exposed instances hide their properties; push from nested layers goes to the outer main; variant property reordering and conflict warnings. Components ~95%/~68% → ~96%/~72%; remaining here 7–14 h → 5–11 h
2026-10-11	minor	Team libraries on figcraft-server (publish under the file, enable by a share link, updates with overrides kept), usage counts per component and file, and swapping a library by names (gap 10)
2026-10-11	minor	Extended collections, variables import/export (JSON, CSS) and gradient stop and variant property bindings landed: styles and variables breadth ~85% → ~92%, ready ~70% → ~72%; remaining here 10–20 h → 7–14 h
2026-10-10	major	Created from the 2026-10-10 re-measure