Semantic Diff Rules

Overview

Whenever components, variants, or styles are synced from Figma, Grails uses its semantic Diff Engine to compare incoming specifications against the currently stored version.

Rather than treating every edit as a generic update, Grails classifies changes into two categories:

Major (Breaking Changes): Modifications that break contracts for consumers in code or existing designs.
Minor (Non-Breaking Changes): Additions, visual evolutions, and token adoptions that remain backward compatible.

1. Component Properties (Props)

Properties define the public contract of your components.

Change	Impact	Severity	Why it matters
Property Removed	A property existed in the previous version but was deleted.	MAJOR	Consumers in code and existing designs rely on this property name. Removing it breaks the interface.
Property Renamed	A property was removed and replaced with a different name.	MAJOR	Consumers querying the property by its former name fail to find it.
Type Changed	The data type of a property changed (e.g., from Text to Boolean).	MAJOR	Incompatible data type breaks code typings and component configurations.
Dropdown Option Removed	An allowed option in an enum/variant property was deleted.	MAJOR	Any design or code instance using that option (e.g., `size="compact"`) no longer resolves.
Property Added	A new property was added with default settings.	MINOR	Additive: existing call sites and instances continue working without changes.
Dropdown Option Added	A new option was added to an existing dropdown.	MINOR	Additive: existing values stay valid.
Default or Config Changed	The default initial value or property config was modified.	MINOR	Safe update: does not break existing contracts or alter explicit selections.
Prop Token Bound / Unbound	A property default was linked to or unlinked from a design token.	MINOR	A prop default is an initial value consumers can override; changing its binding does not break call sites.

2. Anatomy and Internal Structure

Anatomy tracks nested layers, instances, and dynamic prop bindings inside a component.

Change	Impact	Severity	Why it matters
Sub-component Swapped	A nested component instance was replaced with a different component.	MAJOR	Changes the structural contract and props of the nested component.
Layer Removed	An internal structural layer was deleted.	MAJOR	Consumers or parent instances targeting or overriding that layer lose their reference.
Visibility Prop Unbound	An element whose visibility was controlled by a boolean prop stops following it.	MAJOR	Consumers lose control over conditional display.
Text Content Prop Unbound	A text layer whose content was driven by a prop stops following it (becomes static text).	MAJOR	Consumers lose the ability to pass dynamic text to that layer.
Layer Added	A new nested layer or instance was introduced.	MINOR	Additive internal structure.
Layer Modified	Internal structure moved without changing what the component nests or exposes.	MINOR	Structural refinement with no contract impact.
Visibility / Content Bound	A layer gained dynamic visibility or text content controlled by a prop.	MINOR	Additive capability: existing instances keep rendering their default state.

3. Variant Configurations

Variants represent the combinatorial states and configurations of a component set.

Change	Impact	Severity	Why it matters
Variant Removed	A specific variant configuration (e.g., `size=lg, state=disabled`) was deleted.	MAJOR	Any design or code instance referencing that exact configuration cannot resolve it.
Variant Modified	The visual styling, dimensions, or layout of an existing variant changed.	MAJOR	Modifying an existing variant changes what consumers see without opting in.
Variant Added	A new combination was added to the variant matrix.	MINOR	Additive: expands available options while existing configurations keep resolving.

4. Styles and Design Tokens

Grails evaluates visual styles and enforces design token integrity.

Change	Impact	Severity	Why it matters
Token Regression	A style previously bound to a design token was unlinked, falling back to a raw value. It counts when only part of the value loses its token too, such as one side of a padding or one corner of a radius.	MAJOR	Unlinking breaks design system discipline: the style stops following themes and modes, affecting all consumers with no way to opt out.
Tokenized	A raw style value was linked to a design token.	MINOR	Adopting a token is a design system improvement, not a break.
Visual Style Adjusted	A color, spacing, or visual value changed while maintaining its token or presence.	MINOR	Controlled visual evolution.
Style Added or Removed	A style property was added or removed without breaking component references.	MINOR	Visual style refinement.
Inherited Token Value Change	A token referenced by the component changed its underlying value in a mode.	MINOR	Visual update inherited from the token library; the component binding itself remains intact.