openNapkin File Format (.npkd)

The .npkd file format is the native document format for Napukin, a wireframing tool. This folder contains the full specification and resources for working with .npkd files.

Overview

A .npkd file is a plain, uncompressed ZIP archive (STORE mode) with a structured set of JSON documents and optional binary assets inside. It's designed to be:

• Simple — human-readable JSON at its core, easy to inspect and generate
• Portable — a single self-contained file with all assets embedded
• Tooling-friendly — any language with a ZIP library can read or write .npkd files
• AI-friendly — LLMs can generate valid document.json from natural language descriptions of UI layouts

What's Inside a .npkd File

MyDesign.npkd (ZIP archive, STORE/no compression)
├── manifest.json      ← App metadata, version, document name
├── document.json      ← Artboard dimensions, layer tree, comments
├── thumbnail.png      ← Low-res preview of the artboard (max 400×300px)
└── assets/            ← Embedded images (optional, can be empty)
    ├── <assetId>.png
    └── <assetId>.jpg

File	Required	Description
manifest.json	Yes	Identifies the file as a Napukin document with version and creation metadata
document.json	Yes	The full design: artboard size, layers, comments, and asset references
thumbnail.png	No	Preview image, generated on save, max 400×300px
assets/	Yes	Folder for embedded image files, referenced by ID from image layers

Documents in This Folder

Document	Description
npkd-spec.md	Full technical specification — file structure, JSON schemas, layer types, coordinate system, rendering rules
ndkit-spec.md	.ndkit design kit (UI component library) specification — kit packaging, component states, and how kits embed into .npkd documents

Quick Start

Reading a .npkd File

import JSZip from 'jszip';

const zip = await JSZip.loadAsync(file);
const manifest = JSON.parse(await zip.file('manifest.json').async('string'));
const document = JSON.parse(await zip.file('document.json').async('string'));

console.log(manifest.name);              // "My Login Screen"
console.log(document.artboardWidth);     // 393
console.log(document.layers.length);     // 15

Writing a .npkd File

import JSZip from 'jszip';

const zip = new JSZip();
zip.file('manifest.json', JSON.stringify({
  app: 'Napukin',
  version: 1,
  name: 'My Design',
  createdAt: Date.now(),
}));
zip.file('document.json', JSON.stringify({
  name: 'My Design',
  version: 1,
  artboardWidth: 393,
  artboardHeight: 852,
  layers: [/* ... */],
  comments: [],
  assetManifest: [],
}));
zip.folder('assets');

const blob = await zip.generateAsync({ type: 'blob', compression: 'STORE' });
// Save blob as .npkd

Creating One from the Command Line

# Given manifest.json, document.json, and an assets/ folder:
zip -0 MyDesign.npkd manifest.json document.json assets/

Use Cases

• Code-generated wireframes — build .npkd files programmatically from design systems, component libraries, or data models
• AI wireframe generation — give an LLM the spec and it can produce valid .npkd documents from natural language
• Design tooling integration — read .npkd files to extract layer data, generate code, or convert to other formats
• Version control — since the ZIP uses STORE mode and the contents are JSON, diffs are meaningful when extracted

License

The .npkd file format specification is released under the MIT License. You are free to use, implement, and build on it in any project.