Skip to content

Latest commit

 

History

History
85 lines (60 loc) · 3.47 KB

syncing.md

File metadata and controls

85 lines (60 loc) · 3.47 KB

Syncing & safety model

All sync flows live in src/plugin/sync.ts and are driven from the Sync tab. They operate only on the styles the plugin manages (those carrying managedBy: "tailwind-type-sync" metadata).

Drift detection

Before updating a managed style, the engine compares its live Figma values against the lastApplied snapshot in its metadata (hasManualEdits / diffResolved):

  • No drift — live values still match lastApplied. Safe to update.
  • Drift — they differ, so the user manually edited the style after the plugin last wrote it. Handle according to the mode.

Operations

Create missing styles — createMissing

Creates a Text Style for every semantic target that doesn't exist yet. Never modifies anything that already exists. Use it for first run or after adding new semantics. Targets that already exist are reported as skipped (managed) or skippedUnmanaged (a name collision with a hand-made style).

Add Tailwind utility styles — create-utilities

Merges Tailwind's default type scale (text/xs … text/9xl, with the standard per-size line heights) into the config as composites + semantics (src/lib/tailwind-utilities.ts), persists it, then runs createMissing. Idempotent: re-running won't duplicate tokens or overwrite edits.

Adopt existing styles — adoptStyles

Brings hand-made styles whose name matches a target under management by stamping plugin metadata, snapshotting their current values as lastApplied. Appearance is unchanged; a later Safe sync / Review can then pull them onto the token values. Already-managed and non-matching styles are untouched. Adopted styles are reported in the adopted bucket.

Safe sync — syncStyles(config, 'safe')

  • Creates missing styles.
  • Updates managed styles that have no drift.
  • Skips managed styles with drift (your manual edits are preserved).
  • Reports any same-named style that lacks plugin metadata under skippedUnmanaged and never touches it (Adopt it to manage it).

Review changes — reviewStyles → applyReviewDecisions

Computes what would change without writing anything:

  • Missing → reported as "will create".
  • Clean with pending token changes → reported as "will update".
  • Drifted → returned as review items listing the differing fields.

The UI shows each drifted style with Skip / Update anyway toggles; applyReviewDecisions then applies your per-style choices.

Force sync — syncStyles(config, 'force')

Creates missing and overwrites all managed styles, ignoring drift. Still never touches unmanaged styles. This is the explicit "I know, do it anyway" escape hatch (rendered as a destructive button).

Export config TOML

Downloads the current config (tokens + composites + semantics) as a portable TOML file. Import it back from the Tokens tab.

Safety guarantees

  • A style is only ever modified if it carries this plugin's managedBy metadata. User-created styles with no metadata are invisible to sync.
  • Safe mode never overwrites manual edits; only Force (or an explicit Review decision) can.
  • Because designers apply the shared Text Styles, every layer using a style updates automatically through Figma when the style changes.

Result summary

Every operation returns a SyncSummary (created, updated, adopted, skipped, skippedUnmanaged, errors, review) rendered in the Sync tab, plus a one-line figma.notify toast.