| name | penpot-build-screen |
| description | Design production-grade screens in Penpot from a brief, as a senior visual designer — reusing the existing design system (tokens + components) and assembling section by section, never one-shot. Use to create a screen/page/landing/dashboard from a description. NOT for translating existing code (use penpot-build-from-code). Triggers: 'design a dashboard', 'create a landing page', 'design this app screen', 'build a UI from this brief', 'design a settings page', 'mock up a screen in Penpot'. |
| disable-model-invocation | false |
| version | 0.3.0 |
| audiences | ["product-designer"] |
| mode-default | review |
| requires | ["shared/penpot-mcp-tool-reference.md","shared/plugin-api-gotchas.md","shared/tokens-schema.json","shared/naming-conventions.md","shared/state-management.md","shared/modes-and-policies.md","shared/visual-self-review.md","shared/design-quality.md","shared/report-schemas/design-quality-report.schema.json"] |
penpot-build-screen — brief to on-system screen
1. Title + How it works
penpot-build-screen turns a brief into a crafted, on-system screen; every mutation goes through
execute_code; validate visually with export_shape; read structure with
penpotUtils.shapeStructure (full tool surface: shared/penpot-mcp-tool-reference.md). It first
discovers the existing design system (tokens + components via penpot-foundations / the local
library), then builds the screen section by section inside flex Boards, binding tokens and reusing
components — never generating an entire screen in one call.
2. The One Rule That Matters Most
Reuse the system; build incrementally. Prefer existing components and semantic tokens over raw
shapes. Build one section, checkpoint with an export_shape, then continue. If no system exists,
bootstrap only a minimal one (hand off to penpot-foundations for anything substantial).
3. Penpot MCP Tool Reference
Full surface: shared/penpot-mcp-tool-reference.md. Key calls: penpot.createBoard()/addFlexLayout()
for the screen and sections; penpot.library.local.components + comp.instance() to reuse components;
shape.applyToken for token binding; export_shape('selection'|'page') at checkpoints.
4. Plugin API Essentials
Gotcha numbers refer to shared/plugin-api-gotchas.md.
- Screen and sections are Boards with flex layout; compose with append order + gaps + align/justify.
- Reuse components via
component.instance(); don't redraw system parts as raw shapes.
- #3 text auto-sizing — set
growType to auto-width/auto-height AFTER any resize() (which forces fixed).
- #4 flex overrides child x/y — use
layoutChild for stretch/margins.
- Bind colors/spacing/radius/type to semantic tokens, never hardcoded.
- #11 every new Board is born with an OPAQUE WHITE fill — this skill's critical failure mode.
createBoard() ships fills = [{ fillColor: "#FFFFFF", fillOpacity: 1 }]; left in place, a structural wrapper's square white corners poke out behind rounded children (radius looks broken), and layout boards keeping the literal white never flip in dark mode (no token, off-system). decide per board — a board (layout-only chrome: sections, rows, wrappers) gets ; a (screen bg, card, sheet, button) binds a token, never a literal. Default layout containers to transparent ().
