Text

Text combines source content, font selection, layout and paint. Choose an explicit family, weight and style so the same document remains predictable in preview and export.

Text structure

{
  "id": "title",
  "type": "text",
  "payload": {
    "source": { "text": "Neonix JSON V2", "language": "en" },
    "chunks": [{
      "id": "title-chunk",
      "sourceRange": { "start": 0, "end": 14 },
      "textAnchor": "middle",
      "spans": [{
        "id": "title-span",
        "sourceRange": { "start": 0, "end": 14 },
        "font": {
          "families": ["Inter", "sans-serif"],
          "size": 64,
          "weight": 700,
          "style": "normal"
        },
        "fill": "#ffffff"
      }]
    }]
  },
  "frame": { "width": 800, "height": 160 }
}

The families array is an ordered fallback list. The first available family is preferred; later families cover missing glyphs or unavailable styles. Keep a generic fallback such as sans-serif at the end, but use a Neonix system font first for stable export.

Frame and layout

The text frame is the explicit layout area. It controls where lines can wrap and where alignment is resolved; it is not automatically resized to the browser viewport.

• Use a wider frame for a single-line headline.
• Use a fixed width and sufficient height for a paragraph.
• Keep the layer transform separate from text frame geometry.
• Use textAnchor, text alignment and vertical alignment to position shaped lines inside the frame.

The source ranges are UTF-16 offsets and must cover the text spans without overlap. Text source should be NFC-normalized before creating the document.

Gradient text

Text uses the same semantic paint contract as shapes and paths. Put the paint on the text span's fill; do not use a CSS background or an implementation-specific field. Neonix JSON V2 keeps the paint attached to the text span so the text has the same meaning wherever it is previewed or exported.

{
  "type": "text",
  "payload": {
    "source": { "text": "Gradient headline", "language": "en" },
    "chunks": [{
      "id": "headline-chunk",
      "sourceRange": { "start": 0, "end": 17 },
      "textAnchor": "middle",
      "spans": [{
        "id": "headline-span",
        "sourceRange": { "start": 0, "end": 17 },
        "font": {
          "families": ["Inter", "sans-serif"],
          "size": 96,
          "weight": 700
        },
        "fill": {
          "type": "linear-gradient",
          "angle": 0,
          "stops": [
            { "offset": 0, "color": "#22D3EE" },
            { "offset": 0.5, "color": "#60A5FA" },
            { "offset": 1, "color": "#C084FC" }
          ]
        }
      }]
    }]
  },
  "frame": { "width": 1200, "height": 180 }
}

The color is applied only inside the characters; the area outside the text remains transparent. Multiple spans may use different paints; keep each sourceRange aligned with its span so each range receives the intended style.

Gradient types

All gradient types accept stops, optional stopOpacity, spreadMethod (pad, reflect or repeat), gradientUnits and gradientTransform. Stop offsets must be between 0 and 1 and non-decreasing. objectBoundingBox coordinates are normalized to the text layer bounds; userSpaceOnUse coordinates use composition units.

{
  "type": "radial-gradient",
  "cx": 0.5,
  "cy": 0.5,
  "radius": 0.75,
  "gradientUnits": "objectBoundingBox",
  "stops": [
    { "offset": 0, "color": "#FFFFFF" },
    { "offset": 1, "color": "#7C3AED", "stopOpacity": 0.85 }
  ]
}

Keep fonts explicit and available in the asset catalog so a fallback font does not change glyph widths, line breaks or gradient placement.

Font fields

Do not put a CDN URL inside families. The family name selects the face; the asset catalog resolves the actual font bytes.

Use the public font CDN in HTML

The system font CDN is public for GET/HEAD requests. Use an explicit @font-face declaration when authoring HTML outside the app:

<style>
  @font-face {
    font-family: "Inter";
    src: url("https://fonts.neonix.video/inter/Inter_18pt-Regular.ttf") format("truetype");
    font-weight: 400;
    font-style: normal;
    font-display: swap;
  }

  @font-face {
    font-family: "Inter";
    src: url("https://fonts.neonix.video/inter/Inter_18pt-Bold.ttf") format("truetype");
    font-weight: 700;
    font-style: normal;
    font-display: swap;
  }

  .headline {
    font-family: "Inter", sans-serif;
    font-weight: 700;
  }
</style>

The public CDN supports browser GET/HEAD. CORS should allow the HTML page origin to request the font. Use the CDN for known files; it intentionally does not act as a browser directory listing.

Get the complete font catalog

Use the public catalog endpoint to retrieve every enabled system font without authentication:

curl https://www.neonix.video/api/v1/fonts

The public response contains system fonts only. Workspace fonts are available inside the signed-in editor and are intentionally not exposed in this public guide. The public catalog is the source of truth for system fonts; the CDN is the delivery path for a known system-font object.

Deterministic font workflow

1. Select a system family, weight and style from the public catalog or a workspace family from the signed-in editor.
2. In HTML, declare the matching CDN @font-face URL; in Neonix JSON V2, use the family name and weight in the text font object.
3. Keep the same family, weight, style and asset integrity across preview and export.
4. Avoid silently replacing a missing face with a machine-local font.

Font loading failures

If text looks different or a font is missing, check the CDN object URL, CORS response, MIME type, weight/style match and the font catalog integrity value. A fallback family can keep text visible, but it may change glyph widths, line breaks and final composition layout.

See Assets for the asset identity boundary and HTML authoring for the complete HTML document workflow.