Penpot Access And Structure

This note captures the first durable Penpot working model for NEXUS, FnTools, and later FORGE work.

The goal is to make Penpot interaction inspectable and repeatable for both humans and AI, rather than leaving understanding trapped inside one GUI session or one model's memory.

Penpot is important here partly because it pressures the boundary with FnHCI: Penpot components and variants should be usable as design projections without becoming the owner of the cross-platform interaction primitive model.

Why This Matters

Penpot is now important to NEXUS for two related reasons:

  • it is a near-term visual and collaborative surface for Event Modeling and UI work
  • it provides practical integration seams through backend/API access and MCP/plugin access

That means AI should not treat Penpot as "just a drawing app".

Penpot work should be approached as a set of stable, inspectable surfaces:

  • the .penpot file artifact
  • the live backend/API surface
  • the live MCP/plugin surface
  • the GUI as the final visual confirmation surface

Preferred Inspection Order

When AI or humans need to understand a Penpot file or workspace, prefer this order:

  1. durable repo notes that already explain the modeling conventions
  2. offline .penpot file inspection
  3. local Penpot backend/API docs and endpoints
  4. live MCP/plugin interaction against the currently open file
  5. manual GUI inspection only after the structured surfaces above

This keeps Penpot work closer to FORGE:

  • deterministic where possible
  • reviewable
  • easier to translate into scripts, functions, and later F# tooling

What A .penpot File Is

Current Penpot export/import docs describe the exported .penpot format as essentially:

  • a ZIP archive
  • with binary assets alongside readable JSON structure

Penpot also documents that the older binary .penpot format is deprecated.

So the correct current working rule is:

  • do not assume .penpot means opaque binary
  • first verify the actual file you have
  • expect current exported Penpot files to be inspectable with normal archive and text tooling

Useful first commands:

file LaundryLog.penpot
unzip -l LaundryLog.penpot

Your current LaundryLog.penpot file matches that current documented shape. Its archive contents already show:

  • top-level file metadata JSON
  • per-page metadata JSON
  • per-page object JSON files keyed by shape id

First Real Structure Observed

From the current LaundryLog.penpot artifact:

  • top-level file metadata:
  • files/<file-id>.json
  • page metadata:
  • files/<file-id>/pages/<page-id>.json
  • page root object:
  • files/<file-id>/pages/<page-id>/00000000-0000-0000-0000-000000000000.json
  • other shapes and components:
  • files/<file-id>/pages/<page-id>/<shape-id>.json

Examples directly observed from the current file:

  • file metadata includes:
  • name = "LaundryLog"
  • features
  • id
  • projectId
  • teamId
  • modifiedAt
  • version
  • page metadata includes:
  • id
  • name
  • index
  • root/page object includes:
  • type
  • fills
  • shapes
  • geometry and transform data
  • a component-like shape such as Button.Counter includes:
  • type = "frame"
  • isVariantContainer = true
  • layout/flex data
  • child shapes

From the Tokens starter kit v3.penpot example file in tmp/, current exported Penpot files may also include:

  • a dedicated files/<file-id>/tokens.json
  • a manifest features entry such as design-tokens/v1
  • token-set metadata under $metadata
  • theme definitions under $themes

In that real example:

  • the archive manifest was generated by penpot/2.13.0-RC7
  • token-set groups included:
  • Foundations
  • Scale/Linear
  • Scale/Modular
  • Typography
  • Shadows
  • density sets such as Density/Comfortable
  • color sets such as Color theme/Light base, Color theme/Dark base, Color theme/Vibrant, and Color theme/Muted
  • $themes modeled multiple orthogonal theme axes such as:
  • Always enabled
  • Density
  • Color mode
  • Color theme
  • the token model used:
  • foundation-like sets
  • semantic theme sets such as buttonPrimary, layerBase, and input
  • typography tokens
  • active theme selection metadata

That means Penpot token support is already rich enough to pressure our own future token and theming model, not just color swatch exchange.

From the smaller Tokens and breakpoints.penpot example file in tmp/, Penpot tokens can also model responsive breakpoint behavior directly through token sets and themes.

In that real example:

  • token sets included:
  • Global
  • Mobile
  • Tablet
  • Desktop
  • the Global set carried default viewport and text-size tokens
  • the device-specific sets overrode viewport width/height and typography values
  • $themes defined a Breakpoint group with:
  • Mobile
  • Tablet
  • Desktop
  • each breakpoint theme enabled:
  • the shared Global set
  • one device-specific set

That means Penpot is already modeling breakpoint responsiveness as:

  • shared defaults
  • orthogonal theme/set activation
  • selective overrides

not as one giant duplicated token matrix.

The current Penpot community resources also reinforce this direction. The starter-pack thread points users toward:

  • the starter kit template itself
  • a color-token plugin
  • a converter for bringing token files into a Penpot-suitable format
  • tutorials specifically about importing and exporting tokens as JSON

That is a strong sign that Penpot tokens should be treated as a serious interchange surface, not just editor-local styling state.

The breakpoint thread adds an especially important rule from Laura Kalbag:

  • multiple themes can be active simultaneously
  • breakpoint themes can cross-connect with color themes and other theme groups
  • this is meant to work more like CSS rules and media conditions than like one flat combined preset list

That is a very important signal for our future token model because it suggests we should preserve orthogonal theme axes instead of collapsing everything into combined names like light-mobile or dark-desktop.

So the current evidence says:

  • current exported Penpot files store the model as explicit JSON records plus archive-contained assets
  • page and shape hierarchy is materialized on disk
  • component and variant-related information is inspectable without the GUI
  • design tokens are also inspectable as a first-class JSON surface
  • older binary .penpot assumptions should not be treated as the default for current files

Live Access Surfaces

For local Penpot, there are currently two important live access paths:

Backend/API Surface

The local backend/API surface is good for:

  • deterministic system-level operations
  • discovering stable request/response shapes
  • future F# client work such as FnAPI.Penpot

Local example:

  • backend API docs:
  • http://localhost:9001/api/main/doc

MCP And Plugin Surface

The Penpot MCP/plugin surface is good for:

  • working against the currently open file
  • higher-level design-context tasks
  • experimentation while the dedicated NEXUS/FnTools tooling is still emerging

Current local example:

  • plugin manifest:
  • http://localhost:4400/manifest.json
  • MCP endpoint:
  • http://localhost:4401/mcp

Guidance For AI

When working with Penpot, AI should:

  • record important structural discoveries in repo docs
  • prefer extracting inspectable structure over relying on GUI memory
  • capture concrete examples from real .penpot files
  • distinguish clearly between:
  • file artifact structure
  • backend/API behavior
  • MCP/plugin behavior
  • visual interpretation in the GUI

AI should not assume:

  • the GUI is the only source of truth
  • Penpot files are opaque binaries
  • MCP is a substitute for understanding the underlying artifact structure

What Should Become Deterministic Later

This should later turn into stable tool surfaces, likely in FnTools:

  • Penpot file archive inspection helpers
  • normalized extraction of file/page/shape/component structure
  • Penpot API clients and request helpers
  • MCP-backed task helpers for live file interaction
  • later compiler-like transforms from Penpot structures into more deterministic NEXUS/FnTools surfaces