Overview

Variables are named design values — colors, sizes, fonts, image URLs — that you define once
and reuse anywhere on your site. Bind a control to a variable instead of typing a raw value,
and every element using that variable updates the moment you change it. Under the hood, each
variable is a CSS custom property published site-wide on :root, so variables also work in
custom CSS, code elements, and even stylesheets outside Oxygen.

Creating a variable

1. Click the $ icon in the builder toolbar to open the Variables panel.
2. In a collection, click Add Variable and choose a type.
3. The new variable appears as a row with a placeholder name — type a label and a
   value.

The label is automatically slugified into the variable's CSS name — a variable labeled
"Brand Primary" becomes --brand-primary. Hover a variable's row and click the copy
icon to copy var(--brand-primary) for use in CSS.

Variable types

Type	Value	Use for
Color	any color	Brand colors, text colors, backgrounds, borders.
Unit	a number with a CSS unit	Spacing, sizes, border radii, font sizes.
Number	a bare number	Unitless values like line-height, opacity, flex-grow.
Font Family	a font	Typography — define your heading and body fonts once.
Image URL	an image	Recurring imagery like a background texture or default placeholder.

A variable's value can itself reference another variable — for example, a
"Button Background" color variable pointing at "Brand Primary" — so you can build semantic
tokens on top of a base palette.

Using a variable in a design control

Design controls that hold a color, unit, number, font family, or image can be bound to a
variable:

1. Hover the control and click the $ toggle that appears at its top-left corner.
2. Pick a variable from the list. Only variables whose type fits the control are shown — a
   color control lists color variables. Each entry previews its current value, and the
   search box filters by name.

The control now displays the variable as a chip instead of a raw value:

• Clear — hover the chip and click the ✕ to remove the variable from the control.
• Edit — hovering an entry in the chooser reveals a pencil icon that opens the
  variable's name, value, and collection for editing without leaving the control.
• Detach — click the chip to reopen the chooser; the detach icon in its header
  replaces the binding with the variable's current value as a plain, editable setting.
• Jump to the panel — double-click the chip to open the Variables panel.

If a variable that's still in use gets deleted, controls bound to it show a Deleted
chip warning you to unlink it or select a new variable.

Creating a variable on the spot

You don't have to set up variables in advance. Click the + icon at the top of the
chooser to create one right there — name, value, and collection — and it's immediately
applied to the control and available everywhere else.

Editing a variable

Change a variable's value in the Variables panel and every element bound to it updates
live in the canvas. Variable changes are saved when you click Save in the toolbar; if
you close the panel with unsaved changes, Oxygen asks whether to save or discard them.

Renaming is safe for anything bound through the builder: bindings reference the variable
internally by ID, not by name, so chips and overrides keep working when the label (and
therefore the CSS name) changes. Hand-written var(--name) references in custom CSS are
the exception — they use the name itself, so update them after a rename.

Collections

Collections group related variables — a "Brand" collection for colors, a "Spacing"
collection for layout units, and so on. Click Add new collection at the bottom of the
list (or the + icon in the panel header) to create one. Each collection can be:

• Renamed — click its title and type.
• Reordered — drag it above or below other collections.
• Collapsed — click the arrow to tuck it away.
• Exported — the download icon exports just that collection as JSON.
• Deleted — removes the collection and the variables in it (after a confirmation).

History, import, and export

• History — the History button in the Variables panel header shows saved revisions
  of your variables, so you can review and restore an earlier state.
• Export — the panel's Import/Export menu exports all variables as a JSON file;
  individual collections export from their download icon.
• Import — imports a JSON file. Check Merge with the existing Variables to add the
  imported variables alongside what you have; leave it unchecked to replace your variables
  with the file's contents.

Export/import is the way to move a design system between sites — build your token set
once, export it, and import it into every new project.

Tips