Getting started

Overview

Phox Framework turns a handful of decisions into a complete, consistent design system: every colour shade, every heading size, every spacing step and every corner radius, generated from a small configuration and delivered as CSS custom properties.

The configuration lives in one place, in Phox Framework in wp-admin. Saving it does three things at once, always together: it rewrites the framework stylesheet, pushes every token into your page builder's native variable collection, and fills any empty slots in the builder's own Global Settings. Those three representations of your design system can never drift apart, because one save produces all of them.

Getting started

Requirements & installation

1. Install the plugin. Go to Plugins → Add New → Upload Plugin, choose the phox-framework.zip file and click Install Now.
2. Activate it. A Phox Framework item appears in the main admin menu, and the framework stylesheet is generated for the first time.
3. Enter your licence key. On the Licence tab, paste your key and activate. This enables automatic updates.
4. Pick a starting point. Open the Presets tab and apply one, or go straight to Colours and set your own brand colour.

Getting started

Quick start

The fastest route to a working design system is a preset, then one colour.

1. Open Phox Framework from the admin menu and go to the Presets tab.
2. Apply a preset whose feel is closest to the site you are building. Each one sets a palette, a type scale, line heights, fonts, a spacing rhythm and corner radii. You can undo it in one click.
3. Set your brand colour. On the Colours tab, select the Primary slot and paste your brand hex into Source colour. The shade ramp, the hover state and the readable foreground all regenerate as you type.
4. Watch the preview. The panel at the bottom of the screen shows the whole system reacting live, before you save.
5. Save. The stylesheet is rewritten, the tokens are pushed into the builder's variables, and empty Global Settings slots are filled.
6. Use them. Open any page in the builder. Your tokens are in the native variable picker, and a token button sits beside the colour and size controls.

Getting started

The admin interface

Everything lives on one screen, split into tabs.

Getting started

Presets

A preset is a complete starting design. Applying one replaces your palette, type scale, line heights, fonts, spacing rhythm and corner radii in a single step.

What a preset does and does not touch

---

The design system

Colours & shade ramps

The palette is built from slots. Each slot has a job, and you give it one source colour; everything else is generated.

Only enabled slots generate tokens. A fresh install enables Primary, Base and Neutral; switch on the rest as you need them, and switch off any you do not to keep the stylesheet small.

The generated ramp

Each enabled slot produces eight values plus a readable foreground:

Overriding a single shade

Any generated shade can be replaced with a hand-picked colour, for both the light and the dark palette, without disturbing the rest of the ramp. Overridden shades are marked in the interface so you can see at a glance what is generated and what is pinned.

The design system

Ink: readable text

Text colour is the one part of a token system that cannot be a constant. A single global text colour works right up until a section has a dark background, at which point every heading and paragraph inside it becomes unreadable.

So the framework generates five ink roles, and each holds two colours: one for use on a light surface, one for use on a dark one. Each is grown from a palette slot to hit a real WCAG contrast target.

A few of those choices are worth knowing about. Headings sit higher than body copy because a heading at the same contrast as the paragraph beneath it reads as washed out, even when it is technically legible. Muted is grown from Neutral rather than Base, which is what makes it read as a different voice instead of just faded body text. And links keep the brand colour wherever it already clears the target, moving along their own hue only when it does not, so a link still looks like your brand.

The design system

Dark mode

Dark mode is a second palette, grown from the same source colours. Turn it on with Generate a dark palette on the Colours tab.

What happens to a colour depends on what kind of colour it is, and this is the part most systems get wrong. A brand colour holds still. Your brand is your brand at midnight; only the shades around it turn over. A near-neutral inverts, because "the dark grey" has to be dark relative to the page, and the page has turned over.

When dark mode applies

To wire up your own toggle, set the attribute on the html element:

<!-- Force dark -->
<html data-pxf-scheme="dark">

<!-- Force light -->
<html data-pxf-scheme="light">

<!-- Remove the attribute to hand the decision back to the device -->

The design system

Dark areas

A dark area is a section of an ordinary light page that has a dark background. It is not dark mode, and it works whether or not dark mode is switched on.

Mark the section, and every piece of text inside it switches to its dark reading. Headings, body copy, captions and links, at any depth, with nothing inside styled a second time.

<section data-pxf-context="dark" style="background: var(--pxf-surface-dark)">
  <h2>This heading takes its dark value</h2>
  <p>So does this paragraph, and <a href="#">this link</a>.</p>
</section>

In Breakdance and Oxygen you do not write that by hand. Every element gains a Colour context setting with three values:

The design system

Typography

Type is fluid. You set a size for small screens and a size for large ones, and every value in between is interpolated with clamp(). There is no breakpoint to write and no size that is only correct at the widths someone remembered to test.

What you configure

The tokens it produces

Six heading sizes and six text sizes, plus the fonts and line heights:

Per-token overrides

Any individual size can be pinned to a specific minimum and maximum, ignoring the scale. Useful when a scale you like everywhere else produces an H1 that is simply too big.

The design system

Spacing & layout

Spacing works exactly like type: a base value and a ratio, at two viewport anchors, producing a fluid scale.

Rhythm roles

Three named roles point at steps that already exist, rather than adding three more tokens to scroll past:

These three are aliases rather than separate values: each one resolves to a spacing step you already have, which is why they do not appear in the token list or the picker. Point a role at a different step and everything using it moves together. The rhythm is applied automatically inside the builder's Rich Text and Post Content elements and inside ordinary WordPress post content; any other container can opt in with the Smart spacing setting.

The defaults are the classic prose relationship: a heading gets more air above it than paragraphs get between them, and almost none below it, because a heading belongs to the text it introduces rather than floating between two blocks. Retune the scale and the rhythm retunes with it.

The design system

Radius

Corner radius is static, and that is a deliberate claim rather than a simplification. Type and spacing scale with the viewport because reading distance and layout density change with it. A corner does not: a 40px button is a 40px button on a phone and on a desktop, so a corner that grows with the window changes its proportion within a component that has not moved.

Zero is a legal value; square corners are a design choice.

---

In your builder

The token picker

The picker is the part you will use most. A small token button appears beside the builder's own colour and size controls; clicking it opens a searchable list of your tokens, grouped and previewed.

• Hover to preview. Moving through the list previews each token on the real element, so you choose by looking rather than by name.
• Type to filter. The search matches names and groups, so "space" or "primary" narrows the list immediately.
• Only what fits. A colour control is offered colours; a size control is offered sizes. A picker that let you put a spacing token in a colour box would be worse than no picker.
• Multi-value controls work. Padding, margin and other four-sided controls take a token on every side.

Tints

Any colour token can be taken at reduced strength. The picker offers 100, 60, 40, 20, 10 and 5 percent and writes a real color-mix() expression, so the tint follows the token: change the source colour and every tint of it changes too.

How a pick is written

On a builder that supports variables, picking a token writes the builder's own variable binding. The field shows the token's human name, the builder knows the value is a reference rather than a string, and the binding survives a token rename or a prefix change. This is what the Picking a token inserts setting on the Settings tab controls; its other value, Plain CSS you can edit, writes var(--pxf-x) text instead, which is useful when you want to compose on top of the value with a fallback or a calc().

Dark background prompt

Set a section's background to a dark colour and the picker offers to mark that section as a dark area for you, so the text inside it stays readable. Decline it and it stays out of your way.

In your builder

Element settings

Every element in Breakdance and Oxygen gains a Phox section on its Settings tab, in the same place as the builder's own per-element settings. It holds three things, and an element nobody has touched emits no CSS at all, so leaving the section alone costs nothing.

Smart spacing

The rhythm roles already apply on their own inside Rich Text and Post Content, and inside ordinary WordPress post content. That is what Automatic means. Switch it On for any other container, a Section or a Div that stacks headings and text, and its children take the same rhythm: flow space between blocks, heading space above a heading, tight space below one. On also sets the container's row gap to zero, because rhythm and a uniform gap are two answers to the same question, and a container that had both would look broken on exactly the elements you would try this on first. Off removes the space between the element's children, which is how you take the rhythm away from something that would otherwise get it.

A fluid size for one element

The builder's font size control can give an element one size per breakpoint, or a token, which is fluid but over the site's range. Neither says "this hero heading runs from 32px to 96px". Two numbers here do: the smallest the text gets and the largest. Between them it scales with the viewport, using the same interpolation as the site type scale and the same viewport range you set on the Settings tab. The largest field appears once smallest has a value, and nothing is written until both do, because a clamp with one end is a fixed size dressed as a fluid one.

In your builder

Variable sync

Every token is pushed into your builder's own variable collection, so they appear in the native variable pickers throughout the interface, not only in ours.

The sync preserves variable IDs across saves, which is what makes a binding survive a rename. Renaming a token in Phox Framework does not break a page that was bound to it.

In your builder

Global Settings

Breakdance and Oxygen have their own Global Settings panel with colour and typography fields. Phox Framework fills the empty slots there with your tokens, so the builder's own panel reflects your design system instead of its factory defaults.

Who wins

Ownership is decided per property, not per panel. Where you have chosen a value in Global Settings, the framework steps aside for it. Where a slot merely holds the value the sync put there, the framework keeps declaring it, because deferring in that case would mean deferring to itself.

In your builder

Dark Mode Toggle element

An element in the Phox Framework category that lets visitors switch the site between light and dark. It writes the data-pxf-scheme attribute described in Dark mode and remembers the choice.

All three take their colours from your palette by default, and every colour is overridable per element. The Eclipse style also exposes its glow size and transition duration.

The Switch and Icon button styles accept your own sun and moon icons from the builder's icon control. An icon is cleaned to a safe subset of SVG before it is written into the page: shapes, paths, groups, gradients and their presentation attributes stay; scripts, links, external references, styles and event handlers are removed. An icon with nothing drawable left after that falls back to the built-in one.

---

Workflow

The specimen page

The specimen renders your design system against itself: the full type scale with the pixel range each level spans, every colour ramp with hex values and token names, the ink roles graded on a light surface and a dark one, a dark area, buttons and cards, the spacing scale and the corner radii.

It is generated live from your current tokens, so it is always accurate. Two ways to reach it:

• The Specimen toggle in the live preview panel at the bottom of the Colours tab.
• Directly, at yoursite.com/?pxf_preview=specimen. The preview panel has a button that opens exactly that in a new tab, which is worth doing because the page has more to show than a 420px panel can hold.

Workflow

Live preview

The panel at the bottom of the admin screen shows your draft, not what is saved. Drag a colour picker and the preview reacts as you move, before anything is written.

Previewing the Site is the honest test on an established site. Previewing the Specimen is more useful on a new one, where the front page has not been built with these tokens yet and so will not react to them.

Workflow

Settings

Workflow

Export & import

The entire design system is one JSON file. Export it from the Settings tab to move a design between sites, keep it in version control, or take a snapshot before a big change.

Import either by choosing a file or by pasting the JSON. Importing replaces the entire configuration and regenerates the stylesheet immediately.

---

Optional layers

Class modules

Class modules are an optional layer of ready-made component CSS built entirely from your tokens. Every one of them ships switched off. The framework's job is the tokens; these are there if you want components too.

Switch a module on and its tokens join the registry and its CSS joins the stylesheet. Switch it off and both leave again, so an unused module costs nothing.

Optional layers

Utility classes

A separate optional layer of single-purpose classes, also off by default. Four groups, each independently switchable: colours, spacing, text and layout.

/* With the colour utilities on */
<div class="pxf-bg--primary--light pxf-text--base--ultra-dark">

/* A background utility also sets a legible foreground, and a dark one */
/* flips the ink for everything inside it, exactly like a dark area.  */

---

Developer reference

Using tokens in CSS

Every token is a CSS custom property on :root. Use them anywhere you would use a value.

.my-card {
  background: var(--pxf-base-ultra-light);
  color: var(--pxf-text);
  padding: var(--pxf-space-l);
  border: 1px solid var(--pxf-neutral-light);
  border-radius: var(--pxf-radius-m);
  font-size: var(--pxf-text-m);
}

On a default install the framework generates 66 tokens, in six groups:

Enabling more colour slots or class modules adds to that count. The Tokens tab lists every one for the current configuration, which is the authoritative answer for your site.

Developer reference

The cascade layer

Everything the framework emits sits inside a named CSS cascade layer:

@layer phox {
  /* tokens, prose rhythm, module CSS, utilities */
}

Unlayered author styles beat any layer, whatever their specificity. That means your own CSS always wins without a single !important and without counting selectors. It is a floor under your design, not a ceiling over it.

Two things sit deliberately outside the layer, and both for the same reason: they have to win an argument against the builder's own bare-element rules, which are themselves unlayered.

• The base element rules, printed inline late in <head>, which set the body colour and background, heading sizes and link colours.
• The dark mode block.

Both keep their selectors bare (body, h1, a) so anything with a class beats them, which includes every per-element style you set in the builder and every rule you write yourself.

Developer reference

WP-CLI

The framework is fully drivable from a terminal, which is what makes it usable in a deployment script.

# Move a design system between environments
wp phox export > design-system.json
wp phox import design-system.json

# Extract just the tokens as CSS
wp phox tokens --format=css > tokens.css

# Rebuild after a deploy
wp phox regenerate && wp phox sync

Developer reference

Agent tools (MCP)

The framework registers five tools on Breakdance's own MCP server, so an AI assistant can work with your design system directly rather than guessing at hex codes and hard-coding them into pages.

To disable them regardless of the builder's setting:

add_filter( 'phox_framework_abilities', '__return_false' );

Developer reference

Hooks & filters

// Whether the framework registers its agent abilities at all.
add_filter( 'phox_framework_abilities', function ( $enabled ) {
    return $enabled;
} );

// The registered class modules, keyed by slug. Add your own, or
// remove one you never want offered.
add_filter( 'phox_framework_modules', function ( $modules ) {
    return $modules;
} );

Reading the configuration from PHP

use PhoxFramework\Config;
use PhoxFramework\Tokens;

$hex    = Config::value( 'colors.palette.primary.hex' );
$prefix = Config::value( 'prefix', 'pxf' );

// Every token, as records with name, value, type, group and meta.
$tokens = Tokens::all();

// A var() reference for one token, prefix-aware.
$ref = Tokens::ref( 'space-l' );  // var(--pxf-space-l)

Developer reference

Uninstalling

Deleting the plugin through WordPress cleans up after itself, in this order:

1. Global Settings are withdrawn. Any slot still holding exactly the value the sync wrote is emptied. A slot you changed yourself is left alone, because that value is yours.
2. The framework's own variables are removed, after the Global Settings step. Only variables the framework created are touched; one you added by hand inside the Phox collection, or a collection of your own you pointed the sync at, survives. The order matters too: doing it the other way round would leave the panel holding bindings to variables that no longer exist.
3. The generated stylesheet is deleted from the uploads directory.
4. Options are removed: the configuration, the variable map, the stylesheet record, the migration marker, the Global Settings record and the preset undo snapshot.

---

Help

Troubleshooting

My tokens are not in the builder's variable picker

Check the Dashboard's health check first: it reports whether the sync can run at all. The most common causes are that Sync on save is switched off on the Settings tab, or that no supported builder is active, in which case the framework runs in compatibility mode and has nowhere to sync to. If both look right, press Sync to builder on the Dashboard to force a push.

I changed a colour and the front end did not change

Almost always a caching layer holding the old stylesheet. The framework versions the file so browsers pick up changes, but aggressive page caches and CDNs sometimes serve the old one. Clear the site cache, then the CDN. If the Dashboard reports the stylesheet as stale, press Regenerate CSS.

A colour I set in Global Settings is being ignored

It should not be, and this is worth reporting if it happens. The framework decides ownership per property: where you have chosen a value it steps aside, and where a slot merely holds what the sync put there it keeps declaring. If your choice is not winning, check the value in the builder's panel is actually saved rather than showing a placeholder.

Text is unreadable on a dark section

The section needs marking as a dark area. Set Colour context to Dark area on the section, or add data-pxf-context="dark" to it. Setting a dark background colour alone does not tell the framework anything about the text inside, because a dark background is not always meant to carry light text.

Small text is bigger on mobile than on desktop

An inverted fluid range. Your mobile scale ratio is outrunning your body size range, so steps below body size cross over. Bring the two ratios closer together on the Typography tab, or pin the affected size with a per-token override. The audit tool names any token this is happening to.

The Eclipse toggle shows two overlapping circles instead of a crescent

The occluder disc is not matching what is behind the button. It defaults to the page surface token, so this shows up when the toggle sits on a coloured header or a section with its own background. Set Behind the button on the element to that colour.

The token picker is not appearing on a control

The picker only offers itself where a token could actually be used, and it matches types: a colour control is offered colours, a size control is offered sizes. Controls that hold something else, or that hold a locked unit the builder will not accept a variable in, are left alone. In that case use the builder's own variable button, which the picker's decline message points you at.

Something I styled by hand is being overridden

It should not be. Everything the framework emits sits inside a cascade layer, and unlayered author styles beat any layer. The two exceptions are the base element rules and the dark mode block, which sit outside the layer but keep bare selectors, so anything with a class beats them. If your CSS uses a bare body or h1 selector and loads before ours, give it a class or raise its specificity.

I changed the token prefix and my custom CSS broke

Expected. Builder bindings survive a prefix change because they reference variables by ID, but CSS you wrote by hand against --pxf-primary does not. Search your custom CSS and stylesheets for the old prefix and update them, or change the prefix back.

Fatal error mentioning a duplicate constant

Two copies of the plugin are active at once, usually the original folder plus a second upload such as phox-framework-latest. WordPress loads both. Remove one so a single phox-framework folder remains, and update in place rather than adding a parallel folder.

Help

FAQ

Does it work with Oxygen as well as Breakdance?

Both, natively. The token picker, the variable sync, the Global Settings integration and the elements all run in either builder. There is no compatibility mode doing a worse job on one of them.

Do I have to use a preset?

No. Presets are a starting point, not a requirement. Every colour, ratio, size and step is editable, and you can go straight to the Colours tab and build from your own brand colour.

Can I use it without a page builder?

Yes, with a caveat. The stylesheet and the tokens are generated regardless, so you can use them in a theme or in custom CSS. What you lose without a supported builder is the variable sync, the token picker and the Global Settings integration, since all three need a builder to talk to.

Will it fight my existing CSS?

No. Everything sits inside a CSS cascade layer, and unlayered author styles beat any layer, so your own CSS wins without !important and without counting specificity.

How is this different from just writing CSS variables by hand?

Three things a hand-written file cannot do. The tokens are synced into the builder's own variable collection, so they appear in every native picker and a binding survives a rename. The shades and text colours are generated, so you change one hex and the ramp, the hover state and the readable foreground all follow. And a section marked as a dark area repaints every piece of text inside it without you writing a second rule.

Can I rename the tokens?

Yes. The prefix is a setting, and it changes the names in the stylesheet, the builder variables and the picker together. Update any CSS you wrote by hand against the old names.

What happens to my design if I deactivate the plugin?

The framework stylesheet stops loading, so anything using its tokens falls back to whatever value you gave as a fallback, or to nothing. Builder variables synced into the builder remain in the builder's own collection. Deleting the plugin cleans up properly; see Uninstalling.

Does dark mode need a toggle?

Not necessarily. With the default strategy it follows the visitor's system setting on its own. A toggle is for letting people override that, and the plugin ships one.

Are the class modules required?

No, and they all ship switched off. The framework's job is the tokens; the modules are optional component CSS for people who want it. An unused module costs nothing, in tokens or in bytes.

Can an AI assistant change my design system?

Yes, if you have agents enabled in Breakdance. Five tools let it read the system, change part of it, generate a palette from a brand colour, audit for contrast and consistency problems, and rebuild. Writes are behind the same permission as editing by hand, and two of the tools support a dry run. See Agent tools.

Can I move a design system between sites?

Yes, either through Export and import on the Settings tab or with wp phox export and wp phox import.

---

Phox Framework · by Phox Elements · Built for Breakdance and Oxygen. For the latest information visit phox-elements.com.