Self-Hosted, Open-Source Design System

Contribution
1

:hammer_and_wrench: Building a Self-Hosted, Open-Source Design System for Penpot

I’m embarking on an ambitious project: creating a self-hosted Design System solution, conceptually similar to ZeroHeight, but with a firm focus on the open-source ecosystem, particularly Penpot along with Figma (meh).

My core objective is to create a seamless, non-technical experience for designers to contribute to and use the system, along with documentation and alignment with Storybook. Showcasing the component and pattern designs along with rules and tokens.

The Integration Challenge

I’m currently trying to figure out the most straightforward integration path with Penpot. This is where I’ve hit a conceptual roadblock regarding the API access:

  • The existing API token mechanism doesn’t appear to map to a standard REST API endpoint for content retrieval.

  • Integrating via the MCP seems like a deep, specialised path that would likely be beyond the technical comfort zone of the average product designer.

Seeking Guidance

I’m seeking advice or pointers on how to best approach the synchronization or content extraction from Penpot into a documentation tool.

  • Has anyone successfully built a public-facing utility on top of Penpot’s data?

  • Are there more user-friendly/designer-friendly ways to leverage the existing Penpot API or the MCP for automated documentation?

Any insights into the ideal method for creating this solution would be genuinely superb.

More details will follow as I make progress!

4 Likes
2

Looking into this further and similar to how ZeroHeight handles Sketch app, I can create a plugin for Penpot that assists with the syncing process.

3

A plugin could always work. I would recommend against using the REST API (or backend API). The MCP server is also an option and we’re working on making an MCP server available for the general public under design.penpot.app. It’s becoming more and more simple to deploy your own MCP server but it’s true that it requires a bit of tech work.

@juan.delacruz I think we can perhaps do a simple screen recording on how to set-up the Penpot MCP server for oneself. This can help people like @Sulcalibur while we are still WIP with the SaaS version of the MCP Server.

@Sulcalibur I think the MCP Server might be the best approach for your goal. Our internal tests show incredible results with code to design, design to design and design to code workflows (including syncing).

4

I think the MCP is best, I just know many many designers that would be scared off so I was looking at a simpler solution that they could easily dive into.

I’ll try the plugin and see of that syncs the right information across, if not MCP it will have to be, at least for the early stages.

Appreciate your comments and feedback buddy @diacritica

5

The API token it’s coming soon!

1 Like
6

This sounds so cool. It reminds me of this talk from Converge a couple of months ago. Watching it in the room, I instantly thought “it would be so cool to have this design system documentation integration inside of Penpot!”

2 Likes
7

Thanks @LauraKalbag This is great!

I was at the Converge at Brighton last year and it was very inspirational. :slight_smile:

1 Like
8

Hi @Sulcalibur :slight_smile:

I definitely recommend trying out the Penpot MCP locally. It’s a game changer.
I’ve been doing a lot of testing over the last few days and, while it’s not in its most optimized version yet, the amount of things you can do with it in Penpot is incredible. It’s not just ‘design to code,’ but ‘design to design’ as well.

Here is a quick local installation guide and a video where you can see more of what the MCP can do. I hope you find it helpful!!!

  1. Clone the repo: https://github.com/penpot/penpot-mcp

  2. Install the server from the cloned “penpot-mcp” folder (npm-install + npm-run-bootstrap).

  3. Install the plugin in Penpot with the server running—Firefox is recommended (http://localhost:4400/manifest.json).

  4. Install your favorite IDE (like VSCode, Cursor, …)

  5. In your IDE, navigate to: Preferences → IDE Settings → Tools & MCP. (or similar)

  6. Install the Penpot custom server in your IDE using the following configuration:

JSON

{
  "mcpServers": {
    "penpot-mcp": {
      "url": "http://localhost:4401/mcp",
      "type": "http"
    }
  },
  "inputs": []
}

  1. Verify that your IDE has enabled the penpot-mcp server and recognized the 5 tools (check under “Tools & MCP” in your IDE).

  2. Test the connection: Ask the IDE agent to tell you the name of the selected board in Penpot using the MCP (for example).

Recap:

  1. MCP Server running in your local terminal (npm-run-bootstrap).

  2. Plugin running in Penpot and connected to the server (Firefox recommended).

  3. MCP Server enabled in your chosen IDE.

Check this video:

3 Likes
9

Hi @juan.delacruz - Thanks for that detailed breakdown. I have used the MCP and it is superb, I agree. I just feel that a tool such as a Design System documentation the MCP will be ‘too much’ for many designers, especially in a work team environment.

I have it in the back of my mind as a additional solution, but the more simple for the average user, the better from my experience. Most people don’t want to have to learn something new. Not us though, we clearly love it but for the general UX designer at work. That’s a different story.

2 Likes
10

Hi @juan.delacruz is this error message supposed to appear? I’m using Google Antigravity

image
image688×147 6.71 KB

image
image771×213 6.13 KB

11

Guess the “url” was wrong? Changed to “serverURL” and it worked.

image
image733×841 55.4 KB

1 Like
12

Still working through this. First time making something open source that others will be able to download and self host has brought up many new challenges. Ooooft!

One thing the tokens in Penpot are proving to be a lifesaver :heart:

More updates later :slight_smile:

1 Like