> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluid.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract.
> Authenticate with the header Authorization: Bearer <token>; public storefront read endpoints require no auth.
> Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null.
> Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy.
> The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas).
> Successful responses wrap the resource payload alongside a top-level integer status and a meta object.

# Configure a root theme

> Connect theme settings, stored values, CSS variables, and section styles across Fluid's Base, Vox, and Fluid root themes.

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

<Steps>
  <Step title="Declare the setting">
    Add the control to `config/settings_schema.json`.
  </Step>

  <Step title="Store the selected value">
    Add the initial value to `config/settings_data.json`.
  </Step>

  <Step title="Expose a CSS variable">
    Read the setting in `layouts/theme.liquid` and assign it to a CSS custom property.
  </Step>

  <Step title="Use the variable">
    Reference the custom property from global styles, components, or sections.
  </Step>

  <Step title="Test in the editor">
    Change the setting, preview representative templates, and check responsive states.
  </Step>
</Steps>

## Declare settings

Group settings by the job they do. Give each setting a stable ID and a realistic default:

```json theme={null}
[
  {
    "name": "Brand colors",
    "settings": [
      {
        "type": "color",
        "id": "brand_primary",
        "label": "Primary color",
        "default": "#2457d6"
      }
    ]
  }
]
```

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`:

```json theme={null}
{
  "current": {
    "brand_primary": "#2457d6"
  }
}
```

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:

```liquid theme={null}
{% style %}
  :root {
    --brand-primary: {{ settings.brand_primary }};
  }
{% endstyle %}
```

Then consume the variable from reusable styles:

```css theme={null}
.button--primary {
  background: var(--brand-primary);
}
```

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:

```liquid theme={null}
<section
  class="feature-banner"
  style="background: {{ section.settings.background | default: settings.brand_primary }}"
>
  <h2>{{ section.settings.heading }}</h2>
</section>
```

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](/themes/linked-css-variable-presets) to make editor content follow these variables. See the [developer guide](/themes/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.