penpot-workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

From espennilsen/pi, MIT.

More from espennilsen/pi