Core specification

Forma is a canonical intermediate representation of user interfaces. It is not raw source data and not final platform code. It is the normalized layer between design input and downstream reasoning or implementation.

Design goals

Deterministic normalization
Platform-independent representation
Semantic roles for AI reasoning
Token-first styling
Source traceability

Normative language

Producers MUST emit stable node identifiers within document scope.
Producers MUST emit a valid version.
Producers SHOULD emit token references instead of raw values when possible.
Consumers MUST ignore unknown extension fields safely.

Top-level concepts

Document
Node
Layout
Style
SourceRef
Confidence and flags

Minimal document shapeJSON

{
  "version": "1.0.0",
  "source": {
    "tool": "figma",
    "fileId": "abc123"
  },
  "nodes": []
}

Required document fields

version: semantic version string
source: tool origin metadata
nodes: normalized node array

Documents may also include tokens, metadata, extensions, and issues.

Node type	Meaning	Required support	Notes
screen	Top-level screen or frame-like container	Yes	Entry points for agent tasks and exports
component	Reusable component or symbol	Yes	May include variants and slots
container	Non-primitive grouping or layout node	Yes	Used for structural grouping
text	Text primitive	Yes	May include rich text extensions later
image	Image primitive	Yes	Reference only, not embedded binary
icon	Icon primitive	Yes	May reference component or asset