Nib

Tools reference

Recommended design loop

  1. Call get_state before editing. Read the active file, current selection, variables, tree, and schema summary.
  2. Call get_guidelines() to list the design guides and styles.
  3. Load one task guide and one suitable style with their parameters.
  4. Use get_nodes when you need full details for specific nodes.
  5. Make one coherent atomic change with batch_edit.
  6. Call screenshot and judge the rendered pixels—not only the JSON.
  7. Use snapshot_layout to catch clipping, overlap, or incorrect sizing.
  8. Iterate until the composition is clean, then call export.

Do not guess node IDs or edit the .nibs file directly while Nib is open.

Available tools

get_state

Returns the active document path, variables, human selection, and depth-limited tree. The first call from each agent also includes the schema summary.

{ "depth": 3 }

get_nodes

Reads nodes by exact ID, case-insensitive name pattern, or both.

{
  "ids": ["hero1", "title"],
  "namePattern": "hero|cta",
  "searchDepth": 2
}

batch_edit

Applies all operations atomically and saves the document. If any operation is invalid, none are applied.

{
  "ops": [
    {
      "op": "insert",
      "parentId": null,
      "node": {
        "id": "hero1",
        "type": "frame",
        "name": "Launch Hero",
        "x": 0,
        "y": 0,
        "width": 1440,
        "height": 900,
        "layout": "column",
        "padding": 80,
        "gap": 24,
        "fill": "$surface",
        "children": []
      }
    },
    {
      "op": "insert",
      "parentId": "hero1",
      "node": {
        "id": "title",
        "type": "text",
        "content": "Designed with intent.",
        "font": "Newsreader",
        "size": 88,
        "weight": 600,
        "color": "$text"
      }
    }
  ]
}

Supported operations:

  • insert: { op, parentId, index?, node }. Use parentId: null for a top-level node.
  • update: { op, id, props }. Properties are shallow-merged and revalidated.
  • delete: { op, id }. Deletes the node and its subtree.
  • move: { op, id, parentId, index? }. Use parentId: null to move to the document root.
  • set_variable: { op, name, value }.

Important schema rules:

  • Every node ID is exactly five characters using letters, digits, _, or -.
  • Top-level nodes require x and y.
  • Nested nodes must not have x or y; they use their parent frame’s row/column layout.
  • Node types are frame, text, rect, ellipse, image, and svg.
  • Width and height accept numbers, fill, or hug where applicable.
  • Variables are referenced as $name and may contain light/dark values.
  • Fills support colors, variables, solid fills, linear/radial gradients, and images.

screenshot

Returns isolated PNG image content for top-level frames.

{ "nodeIds": ["hero1"], "scale": 1 }

Use screenshots after every meaningful visual change.

export

Writes every requested frame to a directory. PNG supports exact 1×, 2×, and 3× scales; HTML is self-contained.

{
  "nodeIds": ["hero1", "card1"],
  "dir": "/Users/me/Desktop/nib-exports",
  "format": "png",
  "scales": [1, 2, 3]
}

get_guidelines

The guidelines API has three steps:

{}

{ "category": "guide", "name": "graphics" }

{
  "category": "guide",
  "name": "graphics",
  "params": { "preset": "story-9-16" }
}

Task guides: graphics, mobile-app, and landing-page.

Styles: quiet-linen, obsidian-brief, broadsheet-noon, block-signal, cotton-arcade, terminal-ledger, chamber-ivory, and poster-rally.

snapshot_layout

Returns measured renderer positions and sizes for every node under the requested frames.

{ "frameIds": ["hero1"] }

Use it to verify frame bounds, responsive flow, clipping, and spacing after edits.

list_projects

Returns the sidebar tree: projects, loose Open files, nested .nibs paths, and which file is active.

{}

open_file

Opens a .nibs path as the active document (same as choosing it in the sidebar).

{ "path": "/Users/you/project/launch.nibs" }

new_file

Creates a new document with one starter frame and opens it.

{ "projectFolder": "/Users/you/campaign", "name": "spring-ads" }

Or:

{ "path": "/Users/you/Desktop/idea.nibs" }

duplicate_file / rename_file / delete_file

Disk operations on .nibs files. Delete moves to Trash and refuses the active file until you open another document.

{ "path": "/Users/you/campaign/launch.nibs" }

{ "path": "/Users/you/campaign/launch.nibs", "name": "launch-v2.nibs" }

Bundled fonts

These fonts render consistently in the canvas, screenshots, and exports:

  • Geist
  • Geist Mono
  • Inter
  • Newsreader
  • Playfair Display
  • Anton
  • IBM Plex Mono

Nib also loads .ttf and .otf files from an assets/fonts/ folder beside the active .nibs document.