webflow-designer-extension skill

---
name: webflow-designer-extension
description: Build Webflow Designer Extensions that run inside the Webflow Designer. Use when creating, debugging, or modifying Designer Extensions (iframes that interact with Webflow's Designer API). Covers CLI usage, element manipulation, styles, components, pages, variables, assets, error handling, and UI design patterns for Webflow's design system.
license: MIT
compatibility: "create-webflow-extension, @webflow/webflow-cli"
metadata:
  author: "[Ben Sabic](https://bensabic.dev)"
  version: "1.1.0"
---

# Webflow Designer Extension Development

Build extensions that run inside Webflow's Designer as iframes, interacting with the Designer API to manipulate elements, styles, pages, and more.

## Quick Start Workflow

> **Prerequisite:** Register your app in Webflow first — see [references/register-app.md](references/register-app.md). You'll need a Workspace with Admin permissions.

1. **Scaffold**: `npx create-webflow-extension@latest` (interactive prompts for project name, package manager, linter)
2. **Develop**: `cd <name> && pnpm dev` (serves at localhost:1337; also works with npm/yarn/bun)
3. **Test**: Install app on test site via Workspace Settings > Apps & Integrations > Develop
4. **Open**: Press "E" in Designer to open app panel, launch extension
5. **Build**: `pnpm build` for deployment

### CLI Options

```bash
npx create-webflow-extension@latest [project-name] [options]

Options:
  --pm <pnpm|npm|yarn|bun>           Package manager to use (default: pnpm)
  --linter <oxlint|biome|eslint>     Linter to use (default: oxlint)
  --skip-git                         Skip git initialization
  --skip-install                     Skip dependency installation
  --quiet                            Suppress output
```

## Designer API

For all API methods, patterns, and code examples, refer to the reference documentation below. Start with the quick lookup reference for a complete overview:

- **[Designer APIs Reference](references/designer-apis-reference.md)** — all `webflow.*` methods in one table
- **[Elements API](references/elements-api.md)** — element selection, insertion, presets, and the element builder
- **[Styles API](references/styles-api.md)** — creating styles, setting CSS properties, breakpoints, and pseudo-states
- **[Components API](references/components-api.md)** — component definitions, instances, and editing context
- **[Variables API](references/variables-api.md)** — design token variables (colors, sizes, fonts, numbers, percentages)
- **[Error Handling](references/error-handling.md)** — error structure, cause tags, and recovery patterns

## Project Structure

Generated by `create-webflow-extension` (React 19 + TypeScript + Rspack):

```
my-extension/
├── public/
│   └── index.html        # Entry point
├── src/
│   ├── App.tsx           # Main React component
│   ├── main.tsx          # React entry point
│   └── index.css         # Styles
├── webflow.json          # Extension settings
├── rspack.config.ts      # Rspack bundler configuration
├── package.json
└── tsconfig.json
```

## Reference Documentation

Each reference file includes YAML frontmatter with `name`, `description`, and `tags` for searchability. Use the search script to find relevant references quickly:

```bash
# List all references with metadata
python scripts/search_references.py --list

# Search by tag (exact match)
python scripts/search_references.py --tag <tag>

# Search by keyword (across name, description, tags, and content)
python scripts/search_references.py --search <query>
```

### CLI & Tooling

- **[references/create-webflow-extension-reference.md](references/create-webflow-extension-reference.md)**: `create-webflow-extension` scaffolding CLI
- **[references/webflow-cli-reference.md](references/webflow-cli-reference.md)**: Webflow CLI for serving, bundling, and listing extensions

### Designer API

- **[references/designer-apis-reference.md](references/designer-apis-reference.md)**: All APIs and methods in one place (start here)
- **[references/elements-api.md](references/elements-api.md)**: Element manipulation and presets
- **[references/styles-api.md](references/styles-api.md)**: Styling, breakpoints, pseudo-states
- **[references/components-api.md](references/components-api.md)**: Component definitions and instances
- **[references/pages-api.md](references/pages-api.md)**: Page and folder management
- **[references/variables-api.md](references/variables-api.md)**: Design token variables and collections
- **[references/assets-api.md](references/assets-api.md)**: Asset upload and management
- **[references/extension-utilities.md](references/extension-utilities.md)**: Site info, events, notifications, app discovery, authentication
- **[references/error-handling.md](references/error-handling.md)**: Error structure, cause tags, and recovery patterns
- **[references/code-examples.md](references/code-examples.md)**: Cross-API workflow examples combining multiple APIs

### Design & Marketplace

- **[references/design-guidelines.md](references/design-guidelines.md)**: UI design for native Webflow look
- **[references/register-app.md](references/register-app.md)**: Registering a Webflow App and configuring capabilities
- **[references/marketplace-guidelines.md](references/marketplace-guidelines.md)**: Marketplace review criteria (safety, technical, design, branding)
- **[references/app-submission-and-listing.md](references/app-submission-and-listing.md)**: Submitting your app and creating an effective listing
- **[references/faq.md](references/faq.md)**: FAQ and troubleshooting for extensions, marketplace, and common issues

## Scripts

- **`scripts/search_references.py`**: Search reference files by tag, keyword, or list all with metadata

## Assets

- **`assets/webflow-variables.css`**: CSS variables for Webflow's design system colors, typography, and shadows

## Best Practices

1. **Check element capabilities**: Always verify `element.children` before append/prepend, `element.textContent` before text operations
2. **Handle errors gracefully**: Use try/catch with `webflow.notify()` for user feedback — see [Error Handling](references/error-handling.md)
3. **Responsive design**: Test on multiple breakpoints when setting styles — see [Styles API](references/styles-api.md)
4. **Use variables**: Leverage design token variables for consistent theming — see [Variables API](references/variables-api.md)
5. **Subscribe to events**: Use Designer events to keep extension state in sync — see [Extension Utilities](references/extension-utilities.md)
6. **Appropriate sizing**: Use `webflow.setExtensionSize()` for proper panel dimensions — see [Extension Utilities](references/extension-utilities.md)