/penpot-workflow

name: penpot-workflow
description: >
  Manage design work in Penpot — create projects, organize pages, build components, export assets,
  review designs visually, and handle design-to-code handoff. Use when asked to create designs,
  manage Penpot projects, build components, export tokens, set up a new design project,
  review a design, take screenshots, or show what something looks like.

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

| Feature | Create | Modify | Notes | |---------|--------|--------|-------| | Position & size | ✅ | ✅ | x, y, width, height | | Fills | ✅ | ✅ | Array of fill objects | | Border radius | ✅ | ✅ | r1, r2, r3, r4 params | | Shadows | ❌ | ✅ | shadow param, UUID auto-generated | | Blur | ❌ | ✅ | blur param, UUID auto-generated | | Strokes | ✅ | ✅ | strokes param | | Text styling | ✅ | ✅ | fontSize/fontWeight/fontColor on create; textContent on modify | | Opacity | ✅ | ✅ | 0-1 number | | Rotation | ✅ | ✅ | degrees |

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 Playwri