@directededges/specs-from-figma 0.21.0 → 0.22.0

package/dist/Component/Styles/Composites/QuadComposite.d.ts

@@ -0,0 +1,80 @@
+import type { ResolvedConfig } from '@directededges/specs-schema';
+import { FigmaVariableReference } from '../References/index.js';
+import { FigmaElementNode } from '../../Nodes/types.js';
+/** Per-field value: raw number or variable reference */
+export type FieldValue = number | FigmaVariableReference;
+export type QuadValue = number | FigmaVariableReference | QuadComposite;
+export type QuadKind = 'SIDES' | 'CORNERS';
+/** Collected per-field data from Figma node reading */
+export type CollectedField = {
+    logicalKey: string;
+    raw: number | null;
+    variable: FigmaVariableReference | null;
+};
+/**
+ * Generic composite for per-field numeric values (padding, strokeWeight, cornerRadius).
+ * Fields hold raw numbers or FigmaVariableReference instances keyed by logical name.
+ * Serializes to the anova `Sides` or `Corners` output type via data().
+ */
+export declare class QuadComposite {
+    private _fields;
+    private _kind;
+    /** Inherited shorthand default for fields not explicitly set (used during layered diffing) */
+    private _default;
+    /**
+     * Resolve a bound variable for a Figma node property key.
+     */
+    static getVariableForKey(node: FigmaElementNode, figmaKey: string, rawValue: number | null): FigmaVariableReference | null;
+    /**
+     * Collect per-field raw values and variables from a Figma node using a key map.
+     */
+    static collectFields(node: FigmaElementNode, figmaKeyMap: Record<string, string>, includeVariables: boolean, getVariable?: (node: FigmaElementNode, figmaKey: string, raw: number | null) => FigmaVariableReference | null, getRawValue?: (node: FigmaElementNode, figmaKey: string) => number | null): CollectedField[];
+    /**
+     * Build a QuadComposite (or collapse to scalar) from collected per-field data.
+    * Returns a single FigmaVariableReference if all fields share the same variable,
+    * a scalar number if all fields have the same raw value, or a QuadComposite.
+     */
+    static fromFields(fields: CollectedField[], kind: QuadKind): QuadValue;
+    /**
+     * Merge a layered variant object onto a baseline shorthand/object.
+     * Variant wins on overlapping properties.
+     */
+    static merge(base: QuadValue, layer: QuadComposite | null): QuadValue;
+    constructor(fields: Record<string, FieldValue>, kind?: QuadKind);
+    /**
+     * Compare against a baseline. Returns a sparse composite with only changed fields,
+     * or null if no fields differ.
+     */
+    difference(baseline: QuadValue): QuadValue | null;
+    /**
+     * Quad-aware difference router for Style-level union values.
+     *
+     * Returns:
+     * - `undefined` when quad semantics do not apply
+     * - `null` when values participate in quad comparison and are equal
+     * - `QuadValue` when values participate and differ
+     */
+    static differenceValues(current: unknown, baseline: unknown): QuadValue | null | undefined;
+    clone(): QuadComposite;
+    data(config: ResolvedConfig): Record<string, unknown>;
+    /** Returns logical field names that have values */
+    fields(): string[];
+    get kind(): QuadKind;
+    /** True when all fields are plain numbers equal to the given scalar (for default removal) */
+    isEqualToScalar(scalar: number): boolean;
+    /** Get a field value by logical name */
+    get(field: string): FieldValue | undefined;
+    /** Set a field value by logical name */
+    set(field: string, value: FieldValue): void;
+    private fieldValue;
+    private static fieldDiffers;
+    private static cloneFieldValue;
+    private static cloneQuadValue;
+    private static quadFieldValue;
+    private static normalizeQuadOutput;
+    private static keysForKind;
+    private static inferKindFromFields;
+    private static resolveKind;
+    /** Resolve variable names for all FigmaVariableReference fields */
+    resolveVariables(foundations: import('../../../Runtime/Foundations/interfaces.js').FigmaFoundations | undefined): Promise<void>;
+}

package/dist/Component/Styles/Composites/index.d.ts

@@ -0,0 +1,4 @@
+export { QuadComposite } from './QuadComposite.js';
+export type { FieldValue, CollectedField } from './QuadComposite.js';
+export { BiaxialComposite } from './BiaxialComposite.js';
+export type { BiaxialFieldValue, BiaxialValue } from './BiaxialComposite.js';

package/dist/Component/Styles/Primitives/AspectRatioStyle.d.ts

@@ -0,0 +1,34 @@
+import type { AspectRatioValue } from '@directededges/specs-schema';
+import type { FigmaElementNode } from '../../Nodes/types.js';
+export declare class AspectRatioStyle {
+    /**
+     * Evaluate the aspectRatio value for a node:
+     * - If `targetAspectRatio` is set to a non-null Vector → return `{ x, y }` verbatim
+     * - Otherwise → return `null`
+     *
+     * The `targetAspectRatio` property is available on nodes with LayoutMixin.
+     * When the aspect ratio is locked via "Lock aspect ratio" in Figma UI,
+     * this property contains a Vector with x/y values matching the ratio.
+     * When unlocked, the property is `null`.
+     */
+    static value(node: FigmaElementNode): AspectRatioValue | null;
+    /**
+     * Compare two AspectRatioValue instances for equality.
+     * Returns true if they differ, false if they are equivalent.
+     *
+     * @param a - First aspect ratio value (or null)
+     * @param b - Second aspect ratio value (or null)
+     * @returns true if values differ, false if equivalent
+     */
+    static difference(a: AspectRatioValue | null, b: AspectRatioValue | null): boolean;
+    /**
+     * Explicit type guard for AspectRatioValue.
+     * The key must be 'aspectRatio' and the value must be non-null.
+     * Use this guard when narrowing a bare `StyleValue` where the key is known.
+     *
+     * @param key - The style key to check
+     * @param v - The value to check
+     * @returns true if v is a valid AspectRatioValue
+     */
+    static isAspectRatioStyle(key: string, v: unknown): v is AspectRatioValue;
+}

package/dist/Component/Styles/Primitives/BooleanStyle.d.ts

@@ -0,0 +1,6 @@
+import { RawStyle } from '../Style.js';
+import { StyleKey } from "../keys.js";
+import { FigmaElementNode } from '../../Nodes/types.js';
+export declare class BooleanStyle {
+    static value(node: FigmaElementNode, key: StyleKey): RawStyle | null;
+}

package/dist/Component/Styles/Primitives/ColorStyle.d.ts

@@ -0,0 +1,29 @@
+import { RawStyle } from '../Style.js';
+import { StyleKey } from "../keys.js";
+import { FigmaElementNode } from '../../Nodes/types.js';
+import { Gradient } from '../../Gradient/Gradient.js';
+import { Color } from '../../Color/Color.js';
+import type { ProcessingContext } from '../../../Runtime/Context/interfaces.js';
+export declare class ColorStyle {
+    static extractFirstPaint(node: FigmaElementNode, key: string): Paint | undefined;
+    /**
+     * Convert Figma RGB channels (0–1) + opacity to a Color instance.
+     * Always emits sRGB; alpha is omitted when fully opaque.
+     */
+    static toColorValue(color: RGB | (RGB & {
+        a: number;
+    }), opacity?: number): Color;
+    /**
+     * Extract alpha component from a paint or effect as a percentage string suffix.
+     * Retained for future color format configuration (RGBA, HSLA, etc.).
+     */
+    static alpha(color: Paint | Effect): string;
+    /**
+     * Convert a paint or effect color to an HSLA string.
+     * Retained for future color format configuration (RGBA, HSLA, etc.).
+     */
+    static HSLA2(paintOrEffect: Paint | Effect): string;
+    static value(node: FigmaElementNode, key: StyleKey, context?: ProcessingContext): RawStyle | Color | Gradient | null;
+    static styleFromPaints(colorArray: Paint[] | Effect[], context?: ProcessingContext): RawStyle | Color | Gradient | null;
+    private static toHexByte;
+}

package/dist/Component/Styles/Primitives/ConditionalStyle.d.ts

@@ -0,0 +1,30 @@
+import { Conditional, ResolvedConfig } from '@directededges/specs-schema';
+import type { PropPair } from '../../Props/PropPair.js';
+/**
+ * ConditionalStyle — Style primitive for visibility conditionals.
+ *
+ * Stores the content prop name from a validated binding pair.
+ * Builds the Conditional object on serialization via data().
+ */
+export declare class ConditionalStyle {
+    private readonly _contentPropName;
+    private readonly _booleanPropName;
+    constructor(pair: PropPair);
+    /**
+     * The commensurate Figma BOOLEAN prop that drives this element's visibility
+     * (e.g. `showIcon`), as opposed to the content prop referenced in the
+     * serialized condition (e.g. `icon`). Exposed for consumers that render the
+     * binding directly from the model — e.g. the plugin's canvas output renders a
+     * boolean prop pill for it. NOT part of the serialized `data()` shape, so this
+     * does not affect schema output.
+     */
+    get booleanPropName(): string;
+    data(config: ResolvedConfig): Conditional;
+    clone(): ConditionalStyle;
+    /**
+     * Compare two values where at least one may be a ConditionalStyle.
+     * Returns true if different, false if identical.
+     */
+    static difference(a: unknown, b: unknown): boolean;
+    static is(value: unknown): value is ConditionalStyle;
+}

package/dist/Component/Styles/Primitives/CornerStyle.d.ts

@@ -0,0 +1,12 @@
+import { FigmaCorneredNode, FigmaElementNode } from '../../Nodes/types.js';
+import { QuadComposite } from '../Composites/index.js';
+import { FigmaVariableReference } from '../References/index.js';
+import { type ProcessingContext } from '../../../Runtime/Context/interfaces.js';
+/**
+ * Evaluates corner radius from a Figma node.
+ * Returns scalar number (uniform), FigmaVariableReference (uniform token),
+ * CornersQuadComposite (non-uniform), or null (no corners).
+ */
+export declare class CornerStyle {
+    static value(node: FigmaCorneredNode | FigmaElementNode, context?: ProcessingContext): number | FigmaVariableReference | QuadComposite | null;
+}

package/dist/Component/Styles/Primitives/EffectsStyle.d.ts

@@ -0,0 +1,13 @@
+import type { FigmaElementNode } from '../../Nodes/types.js';
+import { FigmaStyleReference } from '../Style.js';
+import { Effects } from '../../Effects/Effects.js';
+import { type ProcessingContext } from '../../../Runtime/Context/interfaces.js';
+export declare class EffectsStyle {
+    /**
+     * Evaluate the effects value for a node:
+     * - If `effectStyleId` is set and entitled → return `FigmaStyleReference` (named style)
+     * - If inline effects exist → return populated `Effects` (shadows gated by context)
+     * - Otherwise → return `null`
+     */
+    static value(node: FigmaElementNode, context?: ProcessingContext): Effects | FigmaStyleReference | null;
+}

package/dist/Component/Styles/Primitives/IconFillStyle.d.ts

@@ -0,0 +1,40 @@
+import { RawStyle } from '../Style.js';
+import { StyleKey } from '../keys.js';
+import { FigmaElementNode } from '../../Nodes/types.js';
+import { Color } from '../../Color/Color.js';
+import { FigmaVariableReference } from '../References/FigmaVariableReference.js';
+import { FigmaStyleReference } from '../References/FigmaStyleReference.js';
+/**
+ * Specialized style handler for icon element `fillColor`.
+ *
+ * Handles the full resolution chain (variable ref → style ref → raw color)
+ * at whichever node has fills, with recursive child drill-down and a
+ * solid-only constraint on fills[0].
+ *
+ * Registered in Style.applySpecializedKeyHandler() so it runs before the
+ * generic applyVariableReference / applyColorStyleReference steps — those
+ * check the top-level node, but icon fills may live on a child.
+ */
+export declare class IconFillStyle {
+    /**
+     * Evaluate fillColor for an icon element.
+     *
+     * Two-pass depth-first search:
+     * 1. Prefer a node with a variable or style binding (richer data).
+     * 2. Fall back to the first node with any solid fill (raw color).
+     *
+     * This ensures intermediate GROUP nodes with unbound fills don't shadow
+     * deeper children that carry the actual variable binding (see #99).
+     */
+    static evaluate(node: FigmaElementNode, key: StyleKey, resolveVariables: boolean): RawStyle | Color | FigmaVariableReference | FigmaStyleReference | null;
+    /** Depth-first walk returning the first matching fill result. */
+    private static walk;
+    /**
+     * Evaluate a single node's fills[0] with full resolution chain.
+     * Order: style ref → variable ref → raw solid color.
+     *
+     * When `bindingsOnly` is true, returns null instead of a raw color —
+     * only style/variable references are returned.
+     */
+    private static evaluateNode;
+}

package/dist/Component/Styles/Primitives/MixedStyle.d.ts

@@ -0,0 +1,5 @@
+import { StyleKey } from "../keys.js";
+import { FigmaElementNode } from '../../Nodes/types.js';
+export declare class MixedStyle {
+    static value<T extends string | number | object>(member: string, node: FigmaElementNode, key: StyleKey): T | string | null;
+}

package/dist/Component/Styles/Primitives/NumberStyle.d.ts

@@ -0,0 +1,7 @@
+import { RawStyle } from '../Style.js';
+import { StyleKey } from '../keys.js';
+import { FigmaElementNode } from '../../Nodes/types.js';
+export declare class NumberStyle {
+    static value(node: FigmaElementNode, key: StyleKey): RawStyle | null;
+    static rounded(value: number | null | undefined): number | null;
+}

package/dist/Component/Styles/Primitives/PaddingStyle.d.ts

@@ -0,0 +1,13 @@
+import { FigmaElementNode } from '../../Nodes/types.js';
+import { QuadComposite } from '../Composites/index.js';
+import { FigmaVariableReference } from '../References/index.js';
+import { type ProcessingContext } from '../../../Runtime/Context/interfaces.js';
+/**
+ * Evaluates padding from a Figma node.
+ * Returns scalar number (uniform), FigmaVariableReference (uniform token),
+ * QuadComposite (non-uniform), or null (no padding).
+ */
+export declare class PaddingStyle {
+    static value(node: FigmaElementNode, context?: ProcessingContext): number | FigmaVariableReference | QuadComposite | null;
+    private static getVariableForKey;
+}

package/dist/Component/Styles/Primitives/StringStyle.d.ts

@@ -0,0 +1,5 @@
+import { StyleKey } from '../keys.js';
+import { FigmaElementNode } from '../../Nodes/types.js';
+export declare class StringStyle {
+    static value(node: FigmaElementNode, key: StyleKey): string | null;
+}

package/dist/Component/Styles/Primitives/StrokeStyle.d.ts

@@ -0,0 +1,12 @@
+import { FigmaElementNode } from '../../Nodes/types.js';
+import { QuadComposite } from '../Composites/index.js';
+import { FigmaVariableReference } from '../References/index.js';
+import { type ProcessingContext } from '../../../Runtime/Context/interfaces.js';
+/**
+ * Evaluates stroke weight from a Figma node.
+ * Returns scalar number (uniform), FigmaVariableReference (uniform token),
+ * SidesQuadComposite (non-uniform), or null (no strokes).
+ */
+export declare class StrokeStyle {
+    static value(node: FigmaElementNode, context?: ProcessingContext): number | FigmaVariableReference | QuadComposite | null;
+}

package/dist/Component/Styles/Primitives/TypographyStyle.d.ts

@@ -0,0 +1,21 @@
+import { FigmaStyleReference } from '../Style.js';
+import { Typography } from '../../Typography/Typography.js';
+import { type ProcessingContext } from '../../../Runtime/Context/interfaces.js';
+/**
+ * TypographyStyle - Minimal orchestration primitive for typography evaluation.
+ *
+ * Priority:
+ * 1. Named text style (textStyleId) → FigmaStyleReference (PRO only)
+ * 2. Inline typography → Typography.evaluate(node, context)
+ *
+ * @see Typography.evaluate() for evaluation implementation
+ * @see EffectsStyle for similar primitive pattern
+ */
+export declare class TypographyStyle {
+    /**
+     * Evaluate typography value for a TextNode.
+     * When not entitled to PRO, named text styles are skipped and inline
+     * Typography is returned instead (with variable references also gated).
+     */
+    static value(node: TextNode, context?: ProcessingContext): FigmaStyleReference | Typography | null;
+}

package/dist/Component/Styles/Primitives/index.d.ts

@@ -0,0 +1,13 @@
+export { AspectRatioStyle } from './AspectRatioStyle.js';
+export { BooleanStyle } from './BooleanStyle.js';
+export { ColorStyle } from './ColorStyle.js';
+export { CornerStyle } from './CornerStyle.js';
+export { EffectsStyle } from './EffectsStyle.js';
+export { IconFillStyle } from './IconFillStyle.js';
+export { MixedStyle } from './MixedStyle.js';
+export { NumberStyle } from './NumberStyle.js';
+export { PaddingStyle } from './PaddingStyle.js';
+export { StringStyle } from './StringStyle.js';
+export { StrokeStyle } from './StrokeStyle.js';
+export { TypographyStyle } from './TypographyStyle.js';
+export { ConditionalStyle } from './ConditionalStyle.js';

package/dist/Component/Styles/Primitives/mapping.d.ts

@@ -0,0 +1,85 @@
+import type { TokenReference } from '@directededges/specs-schema';
+export declare const SIDES_DIRECTION_MAP: {
+    readonly left: "start";
+    readonly right: "end";
+    readonly top: "top";
+    readonly bottom: "bottom";
+};
+export declare const CORNERS_DIRECTION_MAP: {
+    readonly topLeft: "topStart";
+    readonly topRight: "topEnd";
+    readonly bottomRight: "bottomEnd";
+    readonly bottomLeft: "bottomStart";
+};
+export type LogicalSide = typeof SIDES_DIRECTION_MAP[keyof typeof SIDES_DIRECTION_MAP];
+export type LogicalCorner = typeof CORNERS_DIRECTION_MAP[keyof typeof CORNERS_DIRECTION_MAP];
+export declare const PADDING_FIGMA_KEYS: {
+    readonly paddingTop: "top";
+    readonly paddingBottom: "bottom";
+    readonly paddingLeft: "start";
+    readonly paddingRight: "end";
+};
+export declare const STROKE_WEIGHT_FIGMA_KEYS: {
+    readonly strokeTopWeight: "top";
+    readonly strokeBottomWeight: "bottom";
+    readonly strokeLeftWeight: "start";
+    readonly strokeRightWeight: "end";
+};
+export declare const CORNER_RADIUS_FIGMA_KEYS: {
+    readonly topLeftRadius: "topStart";
+    readonly topRightRadius: "topEnd";
+    readonly bottomRightRadius: "bottomEnd";
+    readonly bottomLeftRadius: "bottomStart";
+};
+export declare const STYLE_KEYS_PRIMITIVE_MAP: {
+    TYPOGRAPHY: {
+        keys: string[];
+        tokenType: "typography";
+    };
+    COLOR: {
+        keys: string[];
+        tokenType: "color";
+    };
+    STROKE: {
+        keys: string[];
+        tokenType: "dimension";
+    };
+    CORNER: {
+        keys: string[];
+        tokenType: "dimension";
+    };
+    PADDING: {
+        keys: string[];
+        tokenType: "dimension";
+    };
+    PURE_NUMBER_DIMENSIONLESS: {
+        keys: string[];
+        tokenType: "number";
+    };
+    PURE_NUMBER_DIMENSIONS: {
+        keys: string[];
+        tokenType: "dimension";
+    };
+    MIXABLE_STRING: {
+        keys: string[];
+        tokenType: "string";
+    };
+    PURE_STRING: {
+        keys: string[];
+        tokenType: "string";
+    };
+    BOOLEAN: {
+        keys: string[];
+        tokenType: undefined;
+    };
+    EFFECTS: {
+        keys: string[];
+        tokenType: "effects";
+    };
+    ASPECT_RATIO: {
+        keys: string[];
+        tokenType: undefined;
+    };
+};
+export declare const STYLE_KEYS_PRIMITIVE: Record<string, string>;
+export declare const STYLE_KEY_TO_TOKEN_TYPE: Record<string, TokenReference['$type']>;

package/dist/Component/Styles/References/FigmaStyleReference.d.ts

@@ -0,0 +1,45 @@
+import type { FigmaElementNode } from '../../Nodes/types.js';
+import type { StyleKey } from '../keys.js';
+import type { ResolvedConfig, TokenReference } from '@directededges/specs-schema';
+import type { FigmaFoundations } from '../../../Runtime/Foundations/interfaces.js';
+/**
+ * FigmaStyleReference - instance-based published style binding.
+ *
+ * Represents a node property bound to a published Figma style. Instance-based lifecycle
+ * matches Effects, Gradient, Typography pattern.
+ */
+export declare class FigmaStyleReference {
+    readonly id: string;
+    readonly tokenType: TokenReference['$type'];
+    name?: string;
+    customValue?: Record<string, unknown>;
+    constructor(id: string, tokenType: TokenReference['$type']);
+    /**
+     * Evaluate Figma published style binding for a property.
+     *
+     * Handles:
+     * - textStyleId (top-level property)
+     * - fillStyleId (color styles for fills)
+     * - strokeStyleId (color styles for strokes)
+     *
+     * @param node - Figma node to evaluate
+     * @param key - Style key to check for style binding
+     * @param tokenType - The TokenReference $type for this style reference
+     * @returns FigmaStyleReference instance if bound to published style, null otherwise
+     */
+    static evaluate(node: FigmaElementNode, key: StyleKey, tokenType: TokenReference['$type']): FigmaStyleReference | null;
+    /**
+     * Type guard for FigmaStyleReference instances.
+     */
+    static is(v: unknown): v is FigmaStyleReference;
+    difference(other: FigmaStyleReference): boolean;
+    clone(): FigmaStyleReference;
+    data(config: ResolvedConfig): string | TokenReference;
+    /**
+     * Convert style name to token path using Figma's native `/` separator.
+     * Uses `/` for all profiles to avoid DTCG-restricted characters (`.`, `{`, `}`).
+     * Returns fallback string if name not yet resolved.
+     */
+    private toTokenPath;
+    resolveName(foundations: FigmaFoundations | undefined): Promise<void>;
+}

package/dist/Component/Styles/References/FigmaVariableReference.d.ts

@@ -0,0 +1,61 @@
+import type { FigmaElementNode } from '../../Nodes/types.js';
+import type { StyleKey } from '../keys.js';
+import type { ResolvedConfig, TokenReference } from '@directededges/specs-schema';
+import type { FigmaFoundations } from '../../../Runtime/Foundations/interfaces.js';
+import type { Color } from '../../Color/Color.js';
+export type RawStyle = string | number | boolean;
+/**
+ * FigmaVariableReference - instance-based variable binding.
+ *
+ * Represents a style value bound to a Figma variable. Instance-based lifecycle
+ * matches Effects, Gradient, Typography pattern.
+ */
+export declare class FigmaVariableReference {
+    readonly id: string;
+    readonly rawValue: RawStyle | Color;
+    readonly tokenType: TokenReference['$type'];
+    variableName?: string;
+    collectionName?: string;
+    collectionId?: string;
+    customValue?: Record<string, unknown>;
+    codeSyntax?: {
+        WEB?: string;
+        ANDROID?: string;
+        iOS?: string;
+    };
+    constructor(id: string, rawValue: RawStyle | Color, tokenType: TokenReference['$type']);
+    /**
+     * Evaluate variable binding for a style property.
+     *
+     * @param node - Figma node to evaluate
+     * @param key - Style key to check for variable binding
+     * @param rawValueGetter - Function to compute the raw value if variable binding exists
+     * @returns FigmaVariableReference instance if bound to variable, null otherwise
+     */
+    static evaluate(node: FigmaElementNode, key: StyleKey, rawValueGetter: () => RawStyle | Color): FigmaVariableReference | null;
+    /**
+     * Type guard for FigmaVariableReference instances.
+     */
+    static is(v: unknown): v is FigmaVariableReference;
+    difference(other: FigmaVariableReference): boolean;
+    clone(): FigmaVariableReference;
+    data(config: ResolvedConfig): string | TokenReference;
+    /**
+     * Emit the `TOKEN` shape (`{ $token, $type }`) using the platform's Figma
+     * `codeSyntax` as the `$token`, falling back to the resolved token path when
+     * the token has no code syntax defined for that platform (ADR-051). The
+     * fall-back is a transformer responsibility, not a schema rule.
+     */
+    private codeSyntaxOrTokenFallback;
+    /**
+     * Convert variable name to token path using Figma's native `/` separator.
+     * Uses `/` for all profiles to avoid DTCG-restricted characters (`.`, `{`, `}`).
+     * Returns fallback string if name data not yet resolved.
+     */
+    private toTokenPath;
+    /**
+     * Serialize rawValue for output — Color instances emit ColorObject, primitives pass through.
+     */
+    private serializedRawValue;
+    resolveName(foundations: FigmaFoundations | undefined, includeCollection: boolean): Promise<void>;
+}

package/dist/Component/Styles/References/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Figma reference types for indirection (variables, styles, component properties).
+ *
+ * These types represent pointers to values defined elsewhere in Figma:
+ * - FigmaVariableReference: Design tokens/variables (instance class)
+ * - FigmaStyleReference: Published color/text/effect styles (instance class)
+ * - PropBinding: Component property bindings (instance class, defined in Props/)
+ */
+export type { RawStyle } from './FigmaVariableReference.js';
+export { FigmaVariableReference } from './FigmaVariableReference.js';
+export { FigmaStyleReference } from './FigmaStyleReference.js';
+import { FigmaVariableReference } from './FigmaVariableReference.js';
+import { FigmaStyleReference } from './FigmaStyleReference.js';
+/**
+ * Type guard for FigmaVariableReference instances.
+ */
+export declare function isFigmaVariableReference(v: unknown): v is FigmaVariableReference;
+/**
+ * Type guard for FigmaStyleReference instances.
+ *
+ * Prefer `style.type === 'STYLE'` when the enclosing Style object is available.
+ * Use this guard when narrowing a bare StyleValue.
+ */
+export declare function isFigmaStyleReference(v: unknown): v is FigmaStyleReference;

package/dist/Component/Styles/Style.d.ts

@@ -0,0 +1,88 @@
+import { Style as AnovaStyle } from "@directededges/specs-schema";
+import { AspectRatioValue } from "@directededges/specs-schema";
+import { ConditionalStyle } from './Primitives/ConditionalStyle.js';
+import { FigmaElementNode } from '../Nodes/types.js';
+import { StyleKey } from "./keys.js";
+import { ResolvedConfig } from '@directededges/specs-schema';
+import type { FigmaFoundations } from '../../Runtime/Foundations/interfaces.js';
+import { type ProcessingContext } from '../../Runtime/Context/interfaces.js';
+import { PropBinding } from '../Props/PropBinding.js';
+import { Color } from '../Color/Color.js';
+import { Gradient } from "../Gradient/Gradient.js";
+import { Effects } from '../Effects/Effects.js';
+import { Typography } from '../Typography/Typography.js';
+import { QuadComposite, BiaxialComposite } from './Composites/index.js';
+import { FigmaVariableReference, FigmaStyleReference, RawStyle } from './References/index.js';
+export type { RawStyle };
+export { FigmaVariableReference, FigmaStyleReference };
+export type StyleValue = FigmaVariableReference | FigmaStyleReference | PropBinding | ConditionalStyle | RawStyle | Color | Effects | AspectRatioValue | Gradient | Typography | QuadComposite | BiaxialComposite | null;
+export type StyleType = 'VARIABLE' | 'STYLE' | 'REFERENCE' | 'RAW';
+export declare class Style {
+    readonly key: StyleKey;
+    type: StyleType;
+    value: StyleValue;
+    readonly colorValue?: RGB;
+    private static _context?;
+    static classifyValue(value: unknown): 'VARIABLE' | 'STYLE' | 'RAW';
+    constructor(node: FigmaElementNode, key: StyleKey, context?: ProcessingContext);
+    /**
+     * Compare this Style against a baseline and return the diff.
+     * Returns null if values are identical; a Style with diff value if different.
+     * For composites (Sides/Corners), returns a sparse diff with only changed fields.
+     * For all other types, returns a full clone.
+     */
+    difference(base: Style): Style | null;
+    data(config: ResolvedConfig): AnovaStyle;
+    /**
+     * Return a raw, decision-friendly value for this style (without using `.data()`).
+     *
+     * - VARIABLE: returns the captured `rawValue` (the underlying primitive)
+     * - STYLE: returns the style id (string) so consumers can compare deterministically
+     * - REFERENCE: returns the underlying raw value from the PropBinding
+     * - RAW: returns the primitive value directly
+     *
+     * This is intentionally independent of Settings and intended for internal logic
+     * (ex: Output transforms), not serialization.
+     */
+    rawValue(): RawStyle | Color | string | null;
+    /**
+     * Get the $ref for REFERENCE type styles.
+     * Returns null if not a REFERENCE type or if not bound.
+     */
+    reference(): string | null;
+    private raw;
+    /**
+     * Check if using REST API runtime (vs Plugin API)
+     * Centralized detection logic used by all style processors
+     */
+    static isRESTRuntime(): boolean;
+    static figmaName(id: string, foundations: FigmaFoundations | undefined): Promise<string>;
+    /**
+     * Create a deep clone of this Style instance.
+     * Clones the value object to prevent shared references.
+     *
+     * @returns A new Style instance with cloned value
+     */
+    clone(valueOverride?: StyleValue): Style;
+    /**
+     * Set a binding reference for this style.
+     * When bound, the style will emit a $ref instead of its value.
+     * The actual value is preserved in rawValue for rendering purposes.
+     * @param ref The $ref path
+     * @param rawValue The underlying raw value for rendering
+     */
+    setBinding(ref: string, rawValue: RawStyle): void;
+    /**
+     * Check if this style is bound to a prop reference.
+     * @returns true if bound, false otherwise
+     */
+    isBound(): boolean;
+    private applyContext;
+    private captureColorValue;
+    private applySpecializedKeyHandler;
+    private assignCompositeValue;
+    private applyVariableReference;
+    private applyColorStyleReference;
+    private applyVisibleBinding;
+    private setValue;
+}