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