html2figma v1.0.3

JSON & public types

The portable handoff, its validator and the public type surface.

Validate incoming JSON

TYPESCRIPT

import { parseDocumentJson, isHtml2FigmaDocument } from 'html2figma';

const json = '{ /* converted document */ }';
const documentAst = parseDocumentJson(json);
const unknownValue: unknown = documentAst;
if (isHtml2FigmaDocument(unknownValue)) console.log(unknownValue.root);

parseDocumentJson(value: string): Html2FigmaDocument parses and validates a JSON string. Invalid syntax throws JSON could not be parsed. Invalid schema throws JSON is not a valid html2figma document. Replace the placeholder with real converted JSON.

isHtml2FigmaDocument(value: unknown): value is Html2FigmaDocument validates an already parsed value without throwing for ordinary invalid JSON-shaped data.

The validator checks typed fields, finite numbers, numeric ranges, unique node/resource IDs, and typed resource references. It does not load images, inspect installed fonts, or prove visual fidelity. Bound input size in your own application.

Document structure

Field	Meaning
`version`	AST schema version, currently literal `1`; distinct from library version `1.0.3`.
`root`	Root `Html2FigmaNode`.
`resources`	Image or SVG resource records.
`warnings`	Aggregate conversion diagnostics.
`metadata`	Optional source URL, viewport dimensions, creation timestamp.

Node types

Html2FigmaNode is a discriminated union of frame, rectangle, text, image, and svg. All nodes carry an ID, name, measured bounds, style, source, warnings and children. Text nodes add text; image/SVG nodes add resourceId; images can have alt.

AstBounds provides x, y, width, height. AstStyle includes optional opacity, fills, strokes, per-corner radius, shadows, typography and supported flex layout metadata. Fields describe supported measured output rather than a complete CSS model.

Root exports

Export	Purpose
`Html2FigmaDocument`, `Html2FigmaNode`	Document and node union.
`AstBounds`, `AstStyle`	Geometry and styles.
`ConvertOptions`	Browser traversal options.
`ConvertWarning`, `RenderWarning`	Diagnostics; render warnings share the conversion warning shape.
`ResourceRef`	ID, image/SVG type, source, optional data and MIME type.
`RenderOptions<Parent>`, `RenderResult<Node>`	Portable generic renderer types.

The installed package’s TypeScript declarations provide complete nested field definitions and literal unions. Your IDE can inspect them directly. Do not import private dist files; use the public entrypoints.

Resource portability

A JSON document is portable only when its referenced assets are accessible. Playground images can use public URLs and data URLs; Gallery presets embed their image assets. Font files and browser authentication are not bundled into JSON.

TYPESCRIPT

type NodeId = string;
interface AstBounds {
    x: number;
    y: number;
    width: number;
    height: number;
}
interface Rgb {
    r: number;
    g: number;
    b: number;
}
interface SolidFill {
    type: "solid";
    color: Rgb;
    opacity: number;
}
interface ImageFill {
    type: "image";
    resourceId: string;
    opacity: number;
    scaleMode: "fill" | "fit" | "crop" | "tile";
}
type AstFill = SolidFill | ImageFill;
interface AstStroke {
    color: Rgb;
    opacity: number;
    weight: number;
    align: "inside" | "center" | "outside";
}
interface AstShadow {
    type: "drop-shadow";
    color: Rgb;
    opacity: number;
    offsetX: number;
    offsetY: number;
    blur: number;
    spread: number;
}
interface AstTextStyle {
    fontFamily: string;
    fontSize: number;
    fontWeight: number;
    fontStyle?: "normal" | "italic";
    lineHeight?: number;
    letterSpacing?: number;
    textAlign?: "left" | "center" | "right" | "justified";
    textDecoration?: "none" | "underline" | "strikethrough";
    textCase?: "upper" | "lower" | "title";
    color?: Rgb;
}
interface AstFlexLayout {
    mode: "horizontal" | "vertical";
    gap: number;
    /** Content insets from the frame edge, including CSS border widths. */
    padding: {
        top: number;
        right: number;
        bottom: number;
        left: number;
    };
    primaryAxisAlignItems: "min" | "center" | "max" | "space-between";
    counterAxisAlignItems: "min" | "center" | "max";
    wraps: boolean;
}
interface AstStyle {
    opacity?: number;
    fills?: AstFill[];
    strokes?: AstStroke[];
    cornerRadius?: {
        topLeft: number;
        topRight: number;
        bottomRight: number;
        bottomLeft: number;
    };
    effects?: AstShadow[];
    text?: AstTextStyle;
    layout?: AstFlexLayout;
}
type WarningSeverity = "info" | "warning" | "error";
interface ConvertWarning {
    code: string;
    message: string;
    severity: WarningSeverity;
    nodeId?: NodeId;
    cssProperty?: string;
    source?: string;
}
type RenderWarning = ConvertWarning;
interface ResourceRef {
    id: string;
    type: "image" | "svg";
    source: string;
    data?: string;
    mimeType?: string;
}
interface AstSource {
    tagName: string;
    path: string;
}
interface BaseAstNode {
    id: NodeId;
    name: string;
    bounds: AstBounds;
    style: AstStyle;
    source: AstSource;
    warnings: ConvertWarning[];
    children: Html2FigmaNode[];
}
interface FrameAstNode extends BaseAstNode {
    type: "frame";
}
interface TextAstNode extends BaseAstNode {
    type: "text";
    text: string;
}
interface RectangleAstNode extends BaseAstNode {
    type: "rectangle";
}
interface ImageAstNode extends BaseAstNode {
    type: "image";
    resourceId: string;
    alt?: string;
}
interface SvgAstNode extends BaseAstNode {
    type: "svg";
    resourceId: string;
}
type Html2FigmaNode = FrameAstNode | TextAstNode | RectangleAstNode | ImageAstNode | SvgAstNode;
interface Html2FigmaDocument {
    version: 1;
    root: Html2FigmaNode;
    resources: ResourceRef[];
    /** Aggregate of node diagnostics; node.warnings retains the local view. */
    warnings: ConvertWarning[];
    metadata: {
        sourceUrl?: string;
        viewport: {
            width: number;
            height: number;
        };
        createdAt: string;
    };
}
interface ConvertOptions {
    includeHidden?: boolean;
    maxDepth?: number;
}
/** Platform-neutral options; use html2figma/render for Figma-specialized types. */
interface RenderOptions<Parent = unknown> {
    parent?: Parent;
    x?: number;
    y?: number;
    loadFonts?: boolean;
}
interface RenderResult<Node = unknown> {
    root: Node;
    nodes: Node[];
    warnings: RenderWarning[];
}

export type { AstBounds as A, ConvertOptions as C, Html2FigmaDocument as H, RenderOptions as R, AstStyle as a, ConvertWarning as b, Html2FigmaNode as c, RenderResult as d, RenderWarning as e, ResourceRef as f };

Try in Playground ↗Report a documentation issue ↗