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
{
"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 instance metadata, variant selections, and slot mappings via node.component |
| container | Non-primitive grouping or layout node | Yes | Used for structural grouping |
| text | Text primitive | Yes | May include optional textRuns spans for rich text (v1) |
| image | Image primitive | Yes | Reference only via node.asset, not embedded binary |
| icon | Icon primitive | Yes | Reference via node.asset or a component relationship |
Semantic roles
node.role is an optional semantic hint for agents and downstream exporters. In v1.1, roles are an open vocabulary string (consumers should not assume a closed enum).
The canonical registry used for interoperability is listed in the machine-readable bundle at spec/normative.json.
Role guidance
- Producers SHOULD emit the most specific role they can justify.
- When uncertain, omit role and emit a role_ambiguous issue.
- Consumers SHOULD treat unknown roles as non-fatal and use fallback heuristics (type + structure).
Component instances
Forma uses type: component for both reusable component definitions and instances. When producers can distinguish these reliably, they SHOULD include the optional component object on the node.
- component.kind: definition | instance
- component.definitionId: id of the component definition node
- component.variant: map of variant keys
- component.slots: map slot → child ids
Why this is optional
Some design tools do not expose component instance relationships consistently. In those cases, producers MAY omit node.component and SHOULD emit flags or issues when instance relationships are unresolved.