Documentation

Installation

1. 1Log in to your OxyDance Pilot dashboard at oxydancepilot.com and download the plugin ZIP file.
2. 2In your WordPress admin, go to Plugins → Add New → Upload Plugin.
3. 3Select the downloaded ZIP file and click Install Now.
4. 4Activate the plugin. It will appear under the Breakdance or Oxygen menu, depending on which builder is active on your site.

License Activation

After installing the plugin, navigate to Breakdance → OxyDance Pilot (or Oxygen → OxyDance Pilot if you use Oxygen Builder) in your WordPress admin sidebar.

1. 1Enter your license key in the format OXYD-XXXX-XXXX-XXXX-XXXX.
2. 2Click Activate. The plugin will verify your key with our server and activate it for your site.
3. 3You will see your plan details, including remaining uses (Free plan) or unlimited status (paid plans).

Setting Up Your AI Provider

OxyDance Pilot is a Bring Your Own Key (BYOK) plugin. No AI credits are included — you connect your own API key from a supported provider and pay the provider directly for usage.

1. 1Open the Breakdance or Oxygen builder on any page.
2. 2Click the "Create with AI" button in the builder toolbar.
3. 3Switch to the Settings tab in the OxyDance Pilot panel.
4. 4Select your AI provider from the dropdown.
5. 5Enter your API key. The key is encrypted with AES-256-CBC and stored securely on your WordPress site.
6. 6Choose a model from the auto-populated model list.

Your API key never leaves your WordPress server. All AI requests go directly from your server to the provider — OxyDance Pilot never sees, intercepts, or stores your key or requests.

AI Providers

OxyDance Pilot supports the following AI providers out of the box:

Choosing a Model

The latest list of models for an AI provider will only be loaded after you enter your API key for that provider. Once you've entered a valid API key, a refresh icon appears next to the model select, allowing you to manually update the list from the provider's API. Until you enter an API key, only AI models that have already been recorded in the database will be shown.

API Key Security

• Keys are encrypted with AES-256-CBC using your WordPress AUTH_KEY salt as the secret.
• Only administrators (manage_options capability) can view or change API keys.
• Non-admin editors see masked keys (e.g. sk-pr••••••3kF9).
• Keys never leave your WordPress server — all AI calls are made server-side via PHP cURL.

Creating Sections with AI

The core feature of OxyDance Pilot: describe what you want in plain language and receive native Breakdance or Oxygen elements ready to edit.

Writing Prompts

Simply describe the section you need. Be as specific as you like — mention colors, layout, number of columns, content type, or any design details. The plugin wraps your prompt with a system prompt that enforces production-quality output: clean HTML structure, BEM-style class naming, responsive breakpoints, and proper CSS.

A pricing section with 3 cards side-by-side.
Each card has a plan name, price, feature list, and CTA button.
Use a dark background with white text. The middle card
should be slightly elevated to highlight the recommended plan.

Prompt Enhancement

Click the Enhance button to expand a short prompt into a detailed design brief. The enhancement uses the same AI provider and respects your active design preset and any uploaded reference images, so the expanded prompt stays consistent with your brand.

Image References

Upload one or more reference images before generating. The plugin sends them as multimodal content to AI providers that support vision (such as GPT-4o, Claude Sonnet, and Gemini). This is useful for recreating an existing design or matching a specific style.

How Generation Works

Understanding the full generation pipeline helps with troubleshooting and explains why your API key, generated content, and prompts are fully private:

• Step 1–3: Your prompt is sent via your WordPress REST API to a PHP handler, which uses cURL to stream the request directly to your chosen AI provider. Your API key is decrypted on the server and included in the request header.
• Step 4–5: The AI response is streamed back to your browser in real-time via Server-Sent Events (SSE). As tokens arrive, the plugin extracts clean HTML, CSS, and JavaScript from the output.
• Step 6–8: The extracted code is sent to our converter service, which transforms it into native Breakdance or Oxygen builder elements. The elements are then automatically pasted into your active editor.

Editing with AI

Beyond generating brand-new sections, OxyDance Pilot can rewrite any element already on your canvas. Select a section, column, heading, button, or any nested element and describe the change you want — the AI edits the exact subtree you picked and keeps the rest of the page untouched.

How to Enter Edit Mode

1. 1Right-click any element on the canvas (or in the Structure panel on the left).
2. 2Choose "Edit with AI" from the context menu.
3. 3A floating dock appears next to the element with a prompt composer. You can also move it into the side panel using the dock header.
4. 4Describe what to change — e.g. "make the heading bigger and darker", "add a third feature card", or "switch this to a dark hero with a glow button".
5. 5Click Send. The element and all its children are sent to the AI, rewritten, re-converted, and replaced in-place in the builder tree.

Design System Stays Locked

Any design system you already have active when you enter edit mode — design preset, site inspiration, global settings, or Headspin tokens — is carried into the edit request. Colors, fonts, spacing tokens, and brand values are preserved; only the specific change you asked for is applied.

Exiting Edit Mode

Click Exit in the dock header (or the edit strip at the top of the Create pane when docked into the side panel) to leave edit mode. Exiting also cancels any in-flight generation and restores the normal Create composer.

Triple Shot Mode

Triple Shot generates three design variations in parallel from a single prompt, then lets you compare them side-by-side and keep the one you like best. Works in both generation mode and edit mode. You choose which three directions to run from a library of built-in presets, or you can author your own.

Built-in Design Directions

OxyDance ships with eight built-in variations. Each one is a polished, production-grade system prompt that steers the AI toward a specific mood and composition approach — the active design system (design preset, site inspiration, globals, or Headspin tokens) always wins for palette and fonts, the variation only shapes layout, treatment, and rhythm.

• Clean & Minimal — Restrained layouts, generous whitespace, light weight typography, hairline dividers. Reference feel: Stripe, Notion, Linear.
• Bold & Cinematic — Dark or inverted palettes, oversized headings, heavy weights, glow accents, dramatic scale. Reference feel: Vercel, Raycast, Framer.
• Creative & Editorial — Asymmetric layouts, typographic pairing, arrow links, pill tags, magazine-spread rhythm. Reference feel: Pentagram, It's Nice That, Monocle.
• Futuristic & Tech — Glassmorphism surfaces, neon accent glows, monospace labels, grid-driven precision. Reference feel: Linear, Arc, Raycast.
• Retro & Vintage — Cream backgrounds, saturated accents, drop caps, double-line dividers, editorial margin notes. Reference feel: Penguin covers, vintage Herman Miller, NYT Style.
• Luxury & Premium — Deep dark backgrounds, metallic accents, serif headings at light weights, wide-tracked labels, restrained rhythm. Reference feel: Rolex, Hermès, Aman Resorts.
• Playful & Bright — Rounded geometry, pill buttons, colorful tags, soft pastel backgrounds, decorative blobs. Reference feel: Duolingo, Headspace, Mailchimp.
• Brutalist & Raw — Zero border-radius, thick 2–3px borders, oversized headings wrapping aggressively, monospace metadata, invert-on-hover buttons. Reference feel: Bloomberg terminal, Balenciaga.com.

Picking Your Three

Open the Settings tab of the OxyDance Pilot panel and scroll to Triple Shot Variations. The first three built-ins are selected by default. Click any card to toggle it — selected cards are marked with the green check and a #1 / #2 / #3 pill showing the run order. Only three can be active at a time; the other cards dim once you've filled all three slots. The full eight-card library is collapsed to the first three by default — use Show more to expand the rest. Selections autosave as soon as a full three is picked and sync back on next page load.

Custom Variations

The built-in library is a starting point — if you have a signature style that shows up across many projects, save it as a custom variation and it joins the picker alongside the built-ins. Click + Add Custom in the Triple Shot Variations section to open the editor.

1. 1Click "+ Add Custom" next to the "X of 3 selected" counter.
2. 2Give the variation a short Name (e.g. “Glassy Aurora”) and a one-line Description that shows under the name on the card.
3. 3Write the Create-mode system prompt — describe MOOD, LAYOUT, VISUAL WEIGHT, TYPOGRAPHY, DETAILS, BUTTONS, SPACING, plus a Reference feel line. This is what the AI follows when generating from scratch.
4. 4Write the Edit-mode system prompt — a shorter, directive-style version that restyles existing markup without changing content or structure.
5. 5Click "Create variation" to save. Your custom entry appears at the bottom of the picker with a "Custom" badge.
6. 6Select it like any built-in. Hover the card to reveal the edit and delete buttons (the icons only appear on custom variations).

How to Run

1. 1Open the Create tab in the OxyDance Pilot panel (or the inline edit dock on the canvas).
2. 2Click the + menu next to the composer and toggle "Triple shot".
3. 3Write your prompt and click Send. Three AI requests fan out in parallel — one per selected variation.
4. 4A comparison modal opens as each variation streams in. Preview each one, then click the one you want to keep.
5. 5The chosen variation is converted and pasted into the builder; the other two are discarded.

Plan Mode

Plan Mode asks a few clarifying questions before generation starts, so the AI can align on what you actually want before writing code. Each question is a short step with pill options, single or multiple choice, an optional free-text field, or a color picker — and every question can be skipped. It should feel like a quick scoping step, never a gate.

How It Works

How to Enable

1. 1Open the Create tab (or the inline edit dock) and click the + menu.
2. 2Toggle "Plan mode". A checkmark appears next to the active chip.
3. 3Write your prompt and click Send. The planner runs and a stepper appears above the composer.
4. 4For each question, choose a pill, type a custom answer, pick a color, or click Skip. Use Back / Next to move between steps.
5. 5When you finish (or skip to the end), your original prompt is enriched with your answers and generation starts.

Plan Mode stacks with Triple Shot: the planner runs once, your answers enrich the prompt, then the three variations are generated from that enriched prompt in parallel.

HTML / CSS / JS Converter

The converter lets you transform any HTML, CSS, and JavaScript code into native Breakdance or Oxygen builder elements — no AI required. It is also the backbone the Create and Edit flows use internally to turn AI output into real builder elements.

Manual Conversion

1. 1Open the OxyDance Pilot panel in the builder and switch to the Convert tab.
2. 2Paste your HTML into the HTML field. Optionally add CSS and JavaScript in their respective fields.
3. 3Decide how styles should land in the builder with the "Use selectors" toggle (see below).
4. 4Click Convert & Insert. The plugin sends your code to the converter service.
5. 5The resulting native builder elements are automatically inserted into your active page.

Style Output: Inline-on-Element vs. Use Selectors

Every element converted by OxyDance needs its styles stored somewhere in the builder. You choose where with the Use selectors toggle, available in the Convert tab and under the + menu in the Create tab / inline edit dock.

Design Presets

Design presets let you define reusable brand guidelines that the AI follows when generating sections.

Creating a Preset

In the Settings tab of the OxyDance Pilot panel, scroll to Design Presets and click Add Preset. You can configure:

• Name — A label for easy identification (e.g. "Brand Dark", "Client X").
• Colors — Primary, secondary, accent, background, and text colors.
• Fonts — Heading and body font families.
• Spacing — Default section padding and element gap values.
• Custom instructions — Free-text rules the AI should follow (e.g. "always use rounded corners", "avoid stock photo language").
• Breakpoints — Custom responsive breakpoint values.

Using a Preset

Before generating, select a preset from the dropdown in the Create tab. The preset rules are automatically injected into the system prompt, so the AI produces output that matches your brand colors, typography, and design conventions.

Site Inspirations

Site Inspirations ship a curated library of well-known brands — each with a hand-written design system document covering their palette, typography scale, spacing rhythm, layout patterns, and visual voice. Pick one and the AI generates output that feels like that brand, instead of a generic AI-template look.

Browsing the Library

The plugin bundles dozens of brands out of the box across tech, finance, automotive, media, and design — companies like Vercel, Linear, Stripe, Anthropic, Apple, Tesla, Figma, Notion, Raycast, Framer, Spotify, and many more.

How to Use

1. 1Open the OxyDance Pilot panel in the builder.
2. 2Click the + menu next to the composer and choose "Site inspiration".
3. 3Search by name or browse the grid and click the brand you want.
4. 4The active inspiration shows up as a chip above the composer. Write your prompt normally — it will be generated in that brand's visual language.
5. 5To clear the selection, click the chip's × or pick "None" from the sub-panel.

You can also pin a default inspiration from the Settings tab under the Site inspiration section — so every new session starts with it already active.

Use Global Settings

Use global settings tells the AI to read your Breakdance or Oxygen Globals panel — colors, typography, buttons, forms, containers, design tokens (variables and collections), element presets, and the entire CSS class library — and generate output that uses your site's design system directly.

What Gets Included

• Colors — every global color you have defined.
• Typography — heading and body font stacks, sizes, weights, line heights.
• Buttons & Forms — default button styles, form input styling.
• Containers — section width, padding, and layout defaults.
• Design tokens & variables — every variable and variable collection the builder knows about.
• Element presets — pre-configured looks for specific element types.
• CSS class library — all your site-wide styled selectors (.navbar, .my-button, etc.) so the AI can reuse them instead of inventing new classes.

How to Enable

1. 1Open the Create tab (or the inline edit dock) and click the + menu.
2. 2Toggle "Use global settings". A chip appears above the composer.
3. 3Generate as usual — the AI receives your Globals data as authoritative style guidance.

Headspin Tokens

If your site uses the Headspin UI plugin, OxyDance can read its full design token set — fluid typography scales, spacing ramps, section-spacing ramps, brand and neutral color schemas — and generate output that drops straight into your Headspin-based design system.

Requirements

What Gets Read

• Heading font sizes — H0 through H6 as fluid clamp() ranges (e.g. --hfs-h1: 39–57 px).
• Text font sizes — L, M, S fluid ranges.
• Spacing scale — XXS through XXL fluid space tokens.
• Section spacing — XXS through XXL section-padding fluid tokens.
• Color schemas — brand and neutral palettes, every step, with matched light/dark values (--hcl-brand-* and --hcl-neutral-*).
• Custom tokens — any additional theme tokens you have saved in Headspin.

How to Enable

1. 1In the Create tab or inline edit dock, open the + menu next to the composer.
2. 2Toggle "Headspin tokens". A chip appears above the composer.
3. 3Generate. The AI receives the full list of your Headspin CSS variables, with descriptions, and uses them (e.g. font-size: var(--hfs-h1)) instead of hard-coded values.

If you have not saved any Headspin tokens to the database yet, OxyDance falls back to Headspin's system default token set — so the toggle still works out of the box on a fresh install.

Generation History

Every AI generation is saved to your WordPress database, associated with the user who created it.

• View history — Switch to the History tab to see all past generations. Each entry shows the prompt, date, provider, model, and token usage.
• Restore — Click a history entry to reload the prompt and output. You can then re-convert and insert it into any page.
• Delete — Remove individual history entries you no longer need.
• Token tracking — Each entry records input and output token counts, helping you track API costs across providers and models.

History is stored in your own WordPress database (wp_oxydance_history table). We never have access to your history or generated content.

Self-Hosted AI

OxyDance Pilot supports connecting to your own AI inference server instead of a cloud provider. This gives you full control over your AI infrastructure — useful for privacy, compliance, cost optimization, or running open-source models.

What Is Self-Hosted AI?

Instead of sending requests to a cloud provider like OpenAI or Anthropic, you run your own AI model server on your infrastructure (or a private cloud) and point OxyDance Pilot at it. Any server that exposes an OpenAI-compatible chat completions endpoint will work.

Compatible Servers

The following self-hosted AI servers are known to work with OxyDance Pilot:

Configuration

1. 1Open the builder and click "Create with AI" to open the OxyDance Pilot panel.
2. 2Go to the Settings tab and select "Self-hosted" as your AI provider.
3. 3Enter the full endpoint URL of your AI server (see the compatible servers table above for examples).
4. 4If your server requires authentication, enter the API key. This is optional — many local servers don't require a key.
5. 5Enter the model name your server exposes (e.g. "llama3.1", "mistral-7b", "codestral").
6. 6Save settings and start generating.

Endpoint URL

The plugin sends requests to the exact URL you enter — nothing is auto-appended or modified. You must provide the full path to your server's chat completions endpoint.

Most OpenAI-compatible servers use the /v1/chat/completions path. Check your server's documentation for the correct endpoint.

# Ollama (default port 11434)
http://your-server:11434/v1/chat/completions

# LM Studio (default port 1234)
http://your-server:1234/v1/chat/completions

# vLLM (default port 8000)
http://your-server:8000/v1/chat/completions

# llama.cpp / LocalAI (default port 8080)
http://your-server:8080/v1/chat/completions

# Jan (default port 1337)
http://your-server:1337/v1/chat/completions

How Self-Hosted Requests Work

Self-hosted AI uses the exact same streaming mechanism as cloud providers. Your WordPress server makes a cURL request to your AI server, streams tokens back via Server-Sent Events, and the output follows the same extraction and conversion pipeline.

Security Considerations

To prevent Server-Side Request Forgery (SSRF) attacks, the plugin validates your endpoint URL when saving settings. The following are blocked:

• Localhost addresses — localhost, 0.0.0.0, [::1]
• Cloud metadata endpoints — 169.254.169.254, metadata.google.internal
• Private IP ranges — All RFC 1918 and reserved IP address ranges
• Non-HTTP(S) schemes — Only http:// and https:// are allowed

Token Limits

Unlike cloud providers where the plugin sets a max_tokens parameter based on the model, self-hosted requests do not include a max token limit. Your server uses its own default context window and output length settings.

API Key

The API key field is optional for self-hosted servers. Many local servers (like Ollama) don't require authentication. If your server does require a Bearer token, enter it in the API key field — it will be encrypted and stored exactly the same way as cloud provider keys.

Permissions

OxyDance Pilot uses WordPress capabilities to control access:

Troubleshooting

Common issues and how to resolve them: