Deep Instance Copy

Copy once. Apply deeply.
Carry nested component state from one configured Figma instance to many matching instances, without detaching them.

---

Large design-system components rarely stay shallow. A table row may contain a cell, which contains a control, which contains an icon, label and stateful variant. Configure one instance correctly and reproducing that state across a screen can become a slow tour through several layers of overrides.

Deep Instance Copy captures the supported state of one source instance and applies it to one or many structurally aligned targets. It keeps the component relationship intact, batches variant changes to avoid invalid intermediate states and reports what happened for each selected target.

This repository is the open-source release of an independently built Figma tool. It is usable as a development plugin today and deliberately documents its current boundary while the matching and preview model is strengthened for a future Figma Community submission.

The workflow it is built for

Imagine a dashboard with twelve instances of the same composed table row. You have configured one reference row with:

• a nested Boolean property switched on;
• several text properties populated;
• a child control moved to a different variant;
• a nested icon or component swapped;
• the same configuration needed across several matching rows.

Deep Instance Copy lets the reference instance become the source of truth for that operation. You copy its configuration, select the targets and apply the state in one pass.

Manual repetition	Deep Instance Copy
Open every target and hunt through nested layers	Configure one source instance
Re-enter text and toggle properties individually	Reapply supported state across a selection
Risk invalid intermediate variant combinations	Batch variant properties atomically
Detach or rebuild when overrides become awkward	Keep targets attached to their components

What the current build transfers

State	Current behaviour
Boolean component properties	Captured and applied when the target property is compatible
Text component properties	Captured and applied, with validation and safe font loading for text overrides
Variant properties	Grouped and applied atomically before other properties
Instance-swap properties	Applied when the destination property can resolve the copied value
Nested instances	Traversed recursively to a configurable depth using structural position paths
Multiple targets	Each selected instance is validated and processed independently
Copied configuration	Stored in Figma client storage until cleared

The plugin does not detach instances or modify main components.

How it works

flowchart LR
    A["Select one configured source"] --> B["Capture supported root state"]
    B --> C["Traverse nested instances"]
    C --> D["Store position paths and component metadata"]
    D --> E["Select matching targets"]
    E --> F["Validate compatibility"]
    F --> G["Apply variants atomically"]
    G --> H["Apply supported nested state"]
    H --> I["Report applied, skipped and failed operations"]

Loading

Why position paths?

Layer names are useful to people but fragile as identifiers. Designers rename layers constantly, and duplicated names are common in large component trees. The current algorithm records a numerical path such as [0, 2, 1]: child 0, then child 2, then child 1. Renaming a layer does not break that route.

The trade-off is equally important: inserting, removing or reordering children can change the destination at a position. The current implementation is most dependable across identical or structurally aligned instances. A future release will validate every path against component identity and property signatures, then use an unambiguous structural fallback when position alone is insufficient.

Why batch variant changes?

Variant properties can depend on one another. Applying them one at a time may temporarily request a combination that does not exist in a component set. Deep Instance Copy groups root and nested variant values and calls Figma's property setter once for each group before applying the remaining properties.

Why store the configuration locally?

Copy and paste are separate selection states in Figma. The captured configuration is serialised into Figma client storage so the source does not need to remain selected. The manifest allows no network domains, and the project operates no server, analytics service or maintainer-controlled data store.

Use it as a development plugin

Requirements

• Figma Desktop
• Node.js 22
• npm, using the committed lockfile

1. Clone and build

git clone https://github.com/kevtoe/deep-instance-copy.git
cd deep-instance-copy
nvm use
npm ci
npm run check

npm run check performs the production build and TypeScript validation. Build output is generated in build/ and is deliberately not committed.

2. Import into Figma Desktop

1. Open the Figma desktop app.
2. Choose Plugins → Development → Import plugin from manifest….
3. Select this repository's manifest.json.
4. Open a test file containing component instances.

3. Copy a source configuration

1. Select exactly one component instance.
2. Run Deep Instance Copy from Development plugins.
3. Choose the traversal depth appropriate for the component.
4. Select Copy configuration.

The panel reports how many component properties, nested instances and text overrides were captured, plus whether the selected depth truncated the tree.

4. Apply it to targets

1. Select one or more structurally aligned target instances.
2. Use Strict for the same component or Flexible for related variants and similar component structures.
3. Select Paste configuration.
4. Review the per-target result in the plugin panel.

Start in a duplicate or public-safe test file. Use Figma Undo immediately if a result is not what you expected.

Compatibility modes

Mode	Intended use	Behaviour
Strict	Exact source and target component identity	Rejects incompatible targets before mutation
Flexible	Variants or closely related structures	Permits bounded differences and reports warnings

The source still contains an experimental legacy Smart path, but it is not a separately implemented matching algorithm and is not part of the supported public promise. Do not rely on it for production files.

Current limitations

This is an honest development release, not a claim of universal copying.

• Position paths are sensitive to inserted, removed or reordered children.
• There is no dry-run preview of every match, skip and conflict yet.
• Variable bindings are detected but deliberately not transferred.
• Arbitrary style copying is experimental and not part of the supported scope.
• Raw text traversal can overlap with text component properties in complex trees.
• Partial-result accounting needs a stricter model than the current success threshold.
• The current build has not completed the public Figma fixture matrix required for a Community submission.

It does not claim AI-powered matching, unlimited depth, universal cross-component compatibility, category originality or measured time savings.

Architecture

src/main.ts                 Figma selection, copy/paste events and result orchestration
src/ui.tsx                  Preact plugin panel and operation feedback
src/algorithms/copy.ts      Root capture, recursive traversal and depth analysis
src/algorithms/paste.ts     Compatibility checks, ordered mutation and result reporting
src/types/interfaces.ts     Stored configuration and message contracts
src/utils/storage.ts        Figma client-storage persistence and migration
src/utils/cache.ts          In-memory path and compatibility caches
manifest.json               Figma permissions, entry points and no-network policy

The main thread owns document access. The Preact UI sends typed events for copy, paste and clear operations. Copying produces a versioned CopiedConfiguration; pasting validates each selected instance and applies changes in a deliberate order so hierarchy-changing properties run before deeper traversal.

Verification direction

The release target is a repeatable matrix rather than a single happy-path demo:

Scenario	Required result
Same component, shallow hierarchy	Supported state applies fully
Same component, deep hierarchy	Traversal remains within the selected depth
Different variant in one component set	Valid variants apply atomically
Multiple compatible targets	Every target receives an independent result
Renamed layers, unchanged structure	Position matching remains stable
Reordered or inserted children	Future validation finds one safe match or skips
Missing nested instance	Skip and report without unrelated mutation
Unrelated component	Reject before mutation
Mixed or unavailable font	Skip the text operation safely and report it
Undo after apply	User-visible changes reverse predictably

Pull requests should describe the Figma fixture used to verify the change and run the release gate:

npm run check

Roadmap to a Figma Community release

1. Separate non-mutating analysis from mutation.
2. Validate position paths with component identity and property signatures.
3. Add structural fingerprints and skip ambiguous destinations.
4. Add a preview of matches, skips, conflicts and unsupported properties.
5. Replace the partial-success threshold with exact per-target accounting.
6. Add automated fixtures for pure matching and planning logic.
7. Publish a public-safe Figma playground file and short demonstration.
8. Complete manual accessibility, stress, undo and compatibility testing.

Community publication will be a separate reviewed release. This repository does not imply that the current development build is already listed by Figma.

Privacy and security

• networkAccess.allowedDomains is set to none.
• The plugin reads only the current Figma selection for each operation.
• The copied configuration stays in Figma client storage until cleared.
• No document data is sent to Kevin To or a third-party service by this project.
• No client project, proprietary component library or credential is included in the public repository.

Use SECURITY.md for sensitive vulnerability reports.

Provenance

Kevin To created Deep Instance Copy after testing available property-copying tools against a deeply nested component workflow and finding that they did not reliably cover the required cases. That is first-hand discovery context, not a claim that every alternative fails for every designer.

The technical centre of this implementation is recursive nested-instance capture, position-based traversal, atomic variant application and one-to-many target processing. AI-assisted development supported iteration and release preparation; product framing, workflow validation and the implementation remain Kevin's independent project.

Deep Instance Copy is not affiliated with, endorsed by or an official product of Figma. Figma is a trademark of Figma, Inc.

Contributing

Focused fixes, tests and matching improvements are welcome. Read CONTRIBUTING.md before opening a pull request. Please keep public claims aligned with verified behaviour and never include private design files, client component structures or credentials in an issue or fixture.

Licence

MIT © 2026 Kevin To.