Skip to main content
Fluid provides three root themes: Base, Vox, and Fluid. Each uses the same configuration flow, even when its available settings and design tokens differ. Use this page to extend that flow without coupling a section to one root theme’s current token catalog.

​
Configuration flow

1

Declare the setting

Add the control to config/settings_schema.json.
2

Store the selected value

Add the initial value to config/settings_data.json.
3

Expose a CSS variable

Read the setting in layouts/theme.liquid and assign it to a CSS custom property.
4

Use the variable

Reference the custom property from global styles, components, or sections.
5

Test in the editor

Change the setting, preview representative templates, and check responsive states.

​
Declare settings

Group settings by the job they do. Give each setting a stable ID and a realistic default:
Keep the ID stable after a theme ships. Templates and stored values refer to it.

​
Seed stored values

Use the same ID in config/settings_data.json:
The schema default describes the control’s default. The settings data represents the root theme’s initial configured value. Keep them aligned when you add a setting.

​
Map settings to CSS variables

Expose design settings once in the layout:
Then consume the variable from reusable styles:
This keeps section markup independent from the root theme’s selected value.

​
Use settings in a section

Use a local section setting for content-specific choices and a global setting for system-wide design:
Prefer a class or CSS variable when a value is reused. Reserve inline styles for values that genuinely belong to one section instance.

​
Work across Base, Vox, and Fluid

Do not assume that similarly named tokens have identical defaults across the three root themes. When you port a section:
  1. Identify the design role, such as primary color or heading size.
  2. Find the equivalent setting in the destination theme.
  3. Update the mapping at the layout boundary.
  4. Keep the section pointed at a stable CSS variable.
  5. Compare the section in every supported breakpoint.
Avoid copying a complete token list from another root theme. Root themes evolve, and an old catalog can advertise variables that the current theme no longer builds.

​
Add a setting safely

Before you publish:
  • Use a unique, descriptive setting ID.
  • Provide a default in both configuration files.
  • Add the CSS-variable mapping when editor content should link to the value.
  • Check existing sections for a conflicting variable name.
  • Test the default and a non-default value.
  • Test Base, Vox, or Fluid specifically rather than assuming their defaults match.
See linked CSS presets to make editor content follow these variables. See the developer guide for the rest of the theme file structure.

​
Troubleshoot configuration

If a setting is missing from the editor, validate the schema structure and confirm the setting belongs to a visible group. If a saved value has no effect, confirm that:
  • settings_data.json uses the same ID as settings_schema.json.
  • theme.liquid reads that ID.
  • The CSS variable is declared before it is used.
  • A more specific selector does not override the value.
  • The section reads the intended global or local setting.