Penpot

What it does

Stoaken keeps a Penpot file's design tokens and a Brand's token sets in step. You see what would change on each side before anything is written, and choose the direction. Approved releases reach Penpot from the release's rollout. Tested against Penpot 2.18.4. The full reference is /docs/penpot.

Before you start

• Penpot 2.x (design tokens), on design.penpot.app or self-hosted over public https.
• A Penpot access token from an account that can edit the file.
• Editor access on the Brand in Stoaken.

Setup

1. In Penpot, open the file and copy its address (https://design.penpot.app/#/workspace?team-id=…&file-id=…).
2. Make a token: your account menu, Your account > Access tokens > Generate new token.
3. In Stoaken, Settings > Penpot: pick the Brand, paste the link and token, Connect. The token is stored encrypted.

Configuration

• Sets, tokens and themes pair by name. Themes go to a "Stoaken" group in Penpot; other groups are left alone.
• Send to Penpot makes paired sets match Stoaken; Bring from Penpot lands changes in the working sets, which ship only when a release is approved.
• Self-hosted Penpot needs the enable-access-tokens flag and an internet-reachable https address.

Try it

Connect an empty Penpot file and press Send: the Brand's sets and themes appear in Penpot's tokens panel. Approve a release and use the Penpot step in its rollout to send it.

Troubleshooting

• The token is refused: it expired or was revoked; generate a new one and reconnect.
• The rollout step won't send: the sets changed since the release. Release those changes first (or undo them).
• A self-hosted address is refused: private and local addresses can't be reached from Stoaken's servers.

Limits

Motion, gradients, borders and stroke styles stay in Stoaken (Penpot has no tokens for them). Text case, text decoration, strings, booleans, percentages and formulas stay in Penpot. Whatever stays behind is never removed by a sync.