/** * Design Spec Parser * * Converts Figma nodes into markdown design specifications * for use as AI coding loop task input. */ import type { FigmaNode, Paint, RGBA } from '../types.js'; export interface SpecOptions { /** Font substitution map (original → Google Fonts alternative) */ fontSubstitutions?: Map; /** Image fill download URLs (imageRef → URL) */ imageFillUrls?: Record; /** Icon node IDs that were exported as SVG (nodeId → filename) */ exportedIcons?: Map; /** Composite visual group node IDs that were rendered as single images (nodeId → image path) */ compositeImages?: Map; /** Composite node IDs that have text overlays (visual-dominant composites) */ compositeTextOverlays?: Set; /** Parent background colors for composites (nodeId → CSS color string). * When a composite is inside a parent frame with a solid fill, the composite * render only includes the inner node — not the parent's background. The agent * needs this color as `background-color` on the container so transparent/ * semi-transparent areas in the composite render blend correctly. */ compositeBackgroundColors?: Map; /** Pixels cropped from the top of composite renders (nodeId → design px). * When a composite overflows above its clipping ancestor, the rendered image * is cropped to show only the visible area. This value is included in the spec * as a CSS fallback offset in case the crop wasn't perfectly applied. */ compositeClipCropTops?: Map; } /** * Detect composite visual groups — overlapping visual layers that should * be rendered as a single image rather than extracted individually. * * Examples: hero backgrounds made of stacked mountain/gradient layers, * photo collages, layered illustrations. * * IMPORTANT: Composites must be PURE visual groups (shapes, images, gradients). * The Figma /images API renders everything visible including text, so if a * composite contains text or content frames, the rendered PNG will have * baked-in text that conflicts with the text extracted in the spec. * * Detection criteria: * 1. No auto-layout (children overlap intentionally) * 2. Multiple children (≥2) * 3. ALL children are purely visual — zero TEXT nodes, zero FRAME/GROUP/COMPONENT * children that contain text (these are content containers, not visual layers) * 4. Container is large enough to be a background element (≥200px both dimensions) * 5. Children actually overlap (bounding box intersection >30%) * 6. Not a direct child of CANVAS (those are page sections, not backgrounds) */ export interface CompositeNodeResult { nodeId: string; name: string; width: number; height: number; /** Node IDs of visual-only children to render (excludes text overlays). Present only for visual-dominant composites. */ visualChildIds?: string[]; /** Whether this composite has text overlays that should be positioned on top */ hasTextOverlays?: boolean; /** Background color of the PARENT frame (not the composite node itself). * The composite render only includes the inner node, so transparent areas * need this color as `background-color` on the container element. */ parentBackgroundColor?: string; /** Pixels to crop from the top of the rendered image (at 1x design scale). * When a composite extends above its clipping ancestor (parent frame with * clipsContent=true), the Figma API still renders the full node bounds. * This value tells source.ts how much overflow to crop after download. */ clipCropTop?: number; } export declare function collectCompositeNodes(nodes: FigmaNode[]): CompositeNodeResult[]; /** * Select the primary frame from a list of canvas children. * * When a Figma page has multiple top-level frames (e.g., "Desktop", "Mobile", * component sheets, copies), we only want the main design frame in the spec. * Otherwise the agent gets duplicate content and implements everything twice. * * Heuristic: pick the visible frame with the largest area (width × height). * This is almost always the primary design artboard. */ export declare function selectPrimaryFrames(children: FigmaNode[]): FigmaNode[]; /** * Convert Figma nodes to a markdown design specification */ export declare function nodesToSpec(nodes: FigmaNode[], fileName: string, options?: SpecOptions): string; /** * Convert Figma RGBA to CSS rgba() or hex */ export declare function rgbaToCss(rgba: RGBA, paintOpacity?: number): string; /** * Format gradient as CSS gradient string */ export declare function formatGradient(paint: Paint): string; //# sourceMappingURL=design-spec.d.ts.map