Penpot Workflow

Penpot Workflow

Step-by-step workflows for managing design work in Penpot via the pi-penpot extension.

Project Setup

When starting a new design project:

1. Create the Penpot project with a clear, matching name (same as the code repo)
2. Set up standard pages:
   • Design System — shared components, tokens, and styles
   • Wireframes — low-fidelity layouts and flows
   • One page per major screen or user flow (e.g., Dashboard, Settings, Onboarding)
3. Define foundations first:
   • Color palette (primary, secondary, neutral, semantic: success/warning/error/info)
   • Typography scale (headings h1-h6, body, caption, label, mono)
   • Spacing scale (aligned with Tailwind: 4px base unit)
   • Border radius tokens
   • Shadow/elevation tokens

Shape Creation

Creating shapes with full styling

Use penpot_page tool actions. All shapes support fills, opacity, and rotation on creation.

Rectangles and frames also support r1-r4 for border radius on creation:

penpot_page add-rectangle fileId=X pageId=Y x=0 y=0 width=200 height=100
  fills=[{fillColor: "#1E293B", fillOpacity: 1}]
  r1=12 r2=12 r3=12 r4=12

Text supports fontSize, fontWeight, fontFamily, fontColor on creation:

penpot_page add-text fileId=X pageId=Y x=0 y=0 width=200 height=40
  text="Hello World"
  fontSize="24" fontWeight="700" fontFamily="sourcesanspro" fontColor="#FFFFFF"

Available font families

• sourcesanspro — Source Sans Pro (default, always available)
• Custom fonts can be uploaded via create-font-variant

Font size and weight are STRINGS

Always pass fontSize and fontWeight as strings: "24" not 24, "700" not 700.

Shape Styling (modify-shape)

After creation, use modify-shape to add advanced styling. First-class params:

Border Radius

penpot_page modify-shape fileId=X pageId=Y shapeId=Z r1=16 r2=16 r3=16 r4=16

• r1 = top-left, r2 = top-right, r3 = bottom-right, r4 = bottom-left

Shadows

penpot_page modify-shape fileId=X pageId=Y shapeId=Z
  shadow=[{
    style: "drop-shadow",
    color: {color: "#000000", opacity: 0.3},
    offsetX: 0, offsetY: 4, blur: 12, spread: 0
  }]

• Styles: drop-shadow, inner-shadow
• UUID is auto-generated if not provided
• Multiple shadows supported (array)

Blur

penpot_page modify-shape fileId=X pageId=Y shapeId=Z
  blur={type: "layer-blur", value: 4}

• Types: layer-blur, background-blur
• UUID is auto-generated

Strokes

penpot_page modify-shape fileId=X pageId=Y shapeId=Z
  strokes=[{strokeColor: "#7C3AED", strokeOpacity: 0.5, strokeWidth: 2, strokeAlignment: "inner"}]

• Alignment: inner, center, outer
• Style (via attrs): solid, dotted, dashed, mixed, none

Text Content (re-style existing text)

penpot_page modify-shape fileId=X pageId=Y shapeId=Z
  textContent={
    type: "root",
    children: [{type: "paragraph-set", children: [{type: "paragraph", children: [{
      text: "Updated text",
      fontFamily: "sourcesanspro",
      fontSize: "32",
      fontWeight: "700",
      fontStyle: "normal",
      fillColor: "#FFFFFF",
      fillOpacity: 1
    }]}]}]
  }

Generic attrs (any shape attribute)

Use attrs as a catch-all for any shape property not covered above:

penpot_page modify-shape fileId=X pageId=Y shapeId=Z
  attrs={hidden: true, blocked: false}

Design Workflow — Best Practices

Step-by-step for polished designs

1. Create shapes with basic geometry + fills + border radius
2. Style shapes with modify-shape: shadows, strokes, blur
3. Create text with proper fontSize/fontWeight/fontColor from the start
4. Re-style text with textContent on modify-shape if needed later
5. Batch work — create all shapes first, then style them (reduces API calls)

Performance tips

• Create shapes in rapid succession (each is one API call)
• Use modify-shape to batch multiple styling changes on one shape (fills + strokes + shadow in one call)
• Always get file features from penpot get-file before manual API calls

What works with the extension tools

Visual Review

When you need to review your own work or the user asks you to review a design, capture actual rendered screenshots from Penpot's viewer.

When to do this

• After creating or modifying designs — always screenshot to verify the result
• When the user says "review", "show me", "how does it look", "screenshot"
• Before handoff — capture final state for documentation

Workflow

1. Get the file and page IDs

penpot get-file fileId=<fileId>

2. Create a share link

penpot create-share-link fileId=<fileId> pages=[<pageId1>, <pageId2>] whoInspect="all"

Share links are required — Penpot's viewer won't render without either authentication or a share token.

3. Screenshot each page with Playwright

The Penpot viewer URL format is:

https://penpot.e9n.dev/#/view?file-id=<fileId>&page-id=<pageId>&section=interactions&index=0&share-id=<shareId>

Use Playwright to screenshot each page URL. Penpot is a complex ClojureScript SPA — wait 6+ seconds after navigation for it to render.

Cleanup: Always close the Playwright browser after capture to prevent leaking Chromium processes:

await browser.close();

Save screenshots to /tmp/penpot-<page-name>.png, then read them to view inline. After viewing, delete the temporary file to avoid accumulating disk usage:

rm /tmp/penpot-<page-name>.png

4. Review what you see

After viewing the screenshot, evaluate:

• Layout — is there wasted space? Are elements aligned to a grid?
• Visual hierarchy — can you immediately tell what's important?
• Consistency — do similar elements (cards, tags, buttons) share the same styling?
• Completeness — are there missing states, empty areas, placeholder content?
• Accessibility — text contrast, touch target sizes, focus indicators
• Polish — border radius consistency, shadow consistency, proper spacing

Component Creation

Follow atomic design methodology: