> ## 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.
> When the same operation exists on more than one surface, use the newest: dated API versions are newer than unversioned ones, and later dates win (v2026-04 > v2025-06 > unversioned v0/v1.1). Fall back to a legacy or unversioned operation only when no newer versioned equivalent exists — the company-v0 notes below list the known superseded operations. /api/company/v1 and /api/v1/... paths are documented in no spec here and must never be used (/api/v1.1/... is distinct and documented in company-v0). Use page/per_page offset pagination only where a spec documents it — in practice the unversioned company-v0 admin surface; every versioned surface uses cursor pagination.
> Navigation menu management is documented in themes/navigation-menus. These unversioned admin endpoints (/api/menus and nested menu_items) are verified against the implementation but are not yet in the synced OpenAPI specs. Use that reference for menu payloads and its flat page/per_page pagination; missing spec coverage does not make these endpoints unavailable.
> 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); api-reference/company-v0.yaml covers the legacy unversioned company admin surface (/api/... paths, bearer-authenticated — company settings and management, customers, users, roles, subscription plans, subscription bundles, subscriptions, media, pages, catch-ups, inventory levels, domains, agreements, and admin order actions). company-v0 caveats: it is the legacy v0 admin contract and its lists use flat page/per_page offset pagination, which is expected there despite the general cursor-pagination rule; where an operation exists in both company-v0 and a versioned spec, prefer the versioned spec — the subscriptions lifecycle (list/create/show/update, cancel, pause, reactivate, resume, retry, skip, failed-cycle-waiver, discounts) and subscription bundles are superseded by checkout-v2026-04, and company pages/media CRUD plus the public pages, categories, products, and media list endpoints are superseded by storefront-v2026-04. Subscription plan management (/api/subscription_plans, resource-wrapped {"subscription_plan": {...}} bodies) exists only in company-v0. api-reference/members-v2025-06.yaml covers the v2025-06 unified Member identity surface (/api/v2025-06/members/... paths, bearer-authenticated — member list/create/show/update, lookup by email/username/external_id/legacy_customer_id, member-type assignment, and the sponsor genealogy read). Prefer it over the customers and reps surfaces when the member type matters: /customers does not serialize member_type. api-reference/analytics-v2026-04.yaml covers the v2026-04 Home dashboard analytics surface (/api/v202604/analytics/dashboard/... paths, bearer-authenticated — read-only endpoints for the Home > Overview, Home > Live, and Home > Field tabs, each accepting an optional country ISO alpha-2 query param that scopes aggregations to a single country).
> api-reference/analytics-v0.yaml covers the unversioned analytics surface that backs the fluid-admin Traffic tab (/api/analytics/... and /api/analytics/traffic/... paths, bearer-authenticated — the legacy shares/views/visitors summary plus traffic overview, ranked campaigns, sources, geographies, flows, and per-rep breakdown, all sharing one reporting-period contract).
> Successful responses wrap the resource payload alongside a top-level integer status and a meta object.
> Portal Definition authoring edits and synchronizes the portal JSON resource graph. Widget Package authoring builds either a company-owned or Droplet-owned Remote DOM package. These are separate contracts; do not imply that one defines the other.
> For Widget Package worker code, use only @fluid-app/portal-sdk/widgets/worker. Use only the Portal Definition and Widget Package workflows and public entry points documented here; do not infer support for undocumented surfaces.
> Every portal function and declarative capability used by a widget must appear in that widget's uses array. Use the same typed function value in uses; do not invent capability-name strings.
> Widget styling must use the portal's semantic theme variables for colors, typography, spacing, radii, borders, focus, and charts whenever a token represents the visual decision. Do not create a separate light or dark palette or duplicate theme controls as widget properties.
> Prefer worker-safe Fluid UI components exported by @fluid-app/portal-sdk/widgets/worker when they fit the interaction. When no exported component fits, use semantic HTML, accessible behavior, and the portal theme variables.
> A Portal Definition push updates the remote working definition. A portal version is an immutable snapshot, and activation is a separate live release operation.

# Theme settings and system screen styles

> Share theme colors and fonts with member system screens, and override selected defaults from your theme layout.

<Warning>
  Member storefront is in a limited pilot. The standard theme-setting attributes described below are available in the existing account screens runtime. **CSS overrides that take precedence over those attributes are planned for v0.4.0 and are not yet released.** Use the override examples only after your company loads a release containing that support.
</Warning>

System screens render inside your member site's theme layout. Fluid supplies the screen body; your theme supplies its surrounding navigation, fonts, and colors. You can share the same theme settings used by custom pages without rebuilding the screen's UI.

There are two parts to the styling contract:

* **Standard settings** supply the screen's default colors and font families through attributes on `<fluid-account-screen>`.
* **CSS overrides**, in the upcoming release, let your layout choose different values for individual screen styles while keeping those attribute defaults.

## Standard theme settings

Define these setting IDs in your theme's settings schema and give them valid defaults. When Fluid renders a system screen, it reads the effective theme settings, including the selected preset, and passes the values below to the screen.

| Appearance          | Theme setting                                           | Screen attribute      | Public CSS override (upcoming)        |
| ------------------- | ------------------------------------------------------- | --------------------- | ------------------------------------- |
| Body font           | `font_family_body`                                      | `font-family`         | `--fluid-account-font-family`         |
| Heading font        | `font_family_heading`                                   | `heading-font-family` | `--fluid-account-heading-font-family` |
| Background          | `color_bg`                                              | `background-color`    | `--fluid-account-background`          |
| Body text           | `color_body`                                            | `text-color`          | `--fluid-account-foreground`          |
| Primary action      | `color_primary`                                         | `primary-color`       | `--fluid-account-primary`             |
| Primary action text | `color_btn_primary_text`, falling back to `color_white` | `primary-text-color`  | `--fluid-account-primary-foreground`  |
| Surface             | `color_surface`, falling back to `color_bg`             | `surface-color`       | `--fluid-account-surface`             |
| Surface text        | `color_body`                                            | `surface-text-color`  | `--fluid-account-surface-foreground`  |
| Muted surface       | `color_surface_2`                                       | `muted-color`         | `--fluid-account-muted`               |
| Muted text          | `color_muted`                                           | `muted-text-color`    | `--fluid-account-muted-foreground`    |
| Border              | `color_border`, falling back to `color_input_border`    | `border-color`        | `--fluid-account-border`              |

Color attributes accept CSS colors. Font attributes accept CSS font-family lists, not font URLs or font objects. Missing, empty, or invalid attribute values leave the runtime's defaults available; they do not create the missing theme settings for you.

Your layout must load the fonts it selects, using its existing font-loading mechanism. Passing a family name does not download the font. Supply readable foreground/background pairs, especially for primary actions and surfaces.

Fluid creates the system screen element for a system page. You do not need to add a second `<fluid-account-screen>` to your layout. Keep the layout's `{{ content_for_header }}` and normal page-content output in place. See [Member page layouts](/themes/member-storefront/member-page-templates#create-the-member-layout).

## Override selected defaults with CSS

<Note>
  This section requires the upcoming override-capable runtime. Earlier runtimes can write attribute colors into the same public inline properties, so an ordinary layout rule does not reliably override them.
</Note>

Add the following rule to the stylesheet loaded by your member layout, or to a `<style>` block in that layout:

```css theme={null}
fluid-account-screen {
  --fluid-account-primary: var(--color-button);
  --fluid-account-primary-foreground: var(--color-button-text);
  --fluid-account-background: var(--color-background);
  --fluid-account-foreground: var(--color-text);
  --fluid-account-font-family: var(--font-body);
}
```

The variables on the right belong to **your theme**. Define them using the theme settings you want the screen to follow. The runtime does not create `--color-button`, `--color-background`, or `--font-body` for you. If your theme already emits those variables, reuse them.

Keep the standard setting IDs and their defaults. Add only the public overrides you need; no additional mapping file or new setting schema is required for the override mechanism itself. This rule does not require `!important`.

For example, override only primary action colors while letting all other styles follow the standard attributes:

```css theme={null}
fluid-account-screen {
  --fluid-account-primary: var(--color-button);
  --fluid-account-primary-foreground: var(--color-button-text);
}
```

To change one screen, scope the selector to its `screen` attribute:

```css theme={null}
fluid-account-screen[screen="messaging"] {
  --fluid-account-surface: var(--color-background);
}
```

Use your own theme's actual variable names. You can also assign a valid literal CSS color or font-family list to a public override.

## How precedence works

In the override-capable runtime, each supported style resolves in this order:

1. The public `--fluid-account-*` property supplied by your theme.
2. The corresponding valid screen attribute, supplied from standard theme settings.
3. The runtime's existing default.

Public properties can come from a rule on the element, inheritance from its layout, or your own inline style. Normal CSS cascade rules decide between multiple theme declarations. The attribute is a fallback and does not overwrite your public property.

The runtime reserves `--fluid-account-default-*` for attribute defaults. Do not set those properties in your theme; use the public properties in the table above.

Removing your override reveals the **latest** attribute value. If an inherited override still applies, remove or adjust that declaration too. Changes to supported attributes update presentation without remounting the screen or clearing its drafts. Changes to referenced CSS variables flow through CSS as their values change.

### Missing variables and invalid values

Keep these cases distinct:

| Override                                                                    | Result in the override-capable runtime                                                                                                            |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| No public override is defined                                               | The valid attribute value applies, then the runtime default if needed.                                                                            |
| `--fluid-account-primary: var(--missing-color)` and the source is undefined | The public override is unavailable, so the attribute fallback can apply.                                                                          |
| `--fluid-account-primary: var(--missing-color, #2563eb)`                    | The explicit CSS fallback `#2563eb` is the override and takes precedence over the attribute.                                                      |
| `--fluid-account-primary: 20px`                                             | The property is defined but is not a valid color. The consuming color declaration becomes invalid; it does not automatically retry the attribute. |

Use valid color and font values and check the result in the browser. A fallback inside `var()` handles an unavailable variable; it is not a general validator for a defined value of the wrong type.

## Builder preview and presets

System screen attributes use the effective settings of the theme being previewed, including unsaved builder settings. Changing a preset or one of the mapped settings can therefore update the screen along with custom theme content when the preview is rendered again.

Put override CSS and its source variables in the **rendered theme layout or its stylesheet inside the preview iframe**. CSS added only to the surrounding admin builder document cannot style the iframe's screen.

A public override remains in control when the attribute changes. For example, if primary color is overridden with `var(--color-button)`, changing only `color_primary` will not change the visible primary color. Change the setting that defines `--color-button`, or remove the override to follow `color_primary` again.

When your theme outputs CSS variables from Liquid settings, those variable declarations must also be refreshed in the preview. An override cannot update a source variable whose rendered value has not changed.

## Scope and limitations

* These settings control semantic colors and font families. They do not add attributes for spacing, font sizes, corner radii, or screen layout.
* The screen uses Shadow DOM. Use the public properties instead of targeting internal component classes from your theme stylesheet.
* The override implementation covers screen surfaces, derived Messaging colors, and dialogs. It does not recolor My Site's embedded website preview or replace user-selected group and avatar colors.
* Your theme layout owns the surrounding page width, height, navigation, and font loading.
* Styling does not change member access rules or authentication.

## Runtime availability

The standard unversioned loader is:

```html theme={null}
<script type="module" src="https://assets.fluid.app/account-screens/account-screens.js"></script>
```

Fluid normally provisions the account screens runtime through the company's global embeds. Do not add another copy if the layout already receives it through `{{ content_for_header }}`.

The unversioned URL follows the latest successfully published release; it does not serve changes just because a PR exists. A version-pinned embed keeps its pinned behavior until updated. CSS-over-attribute precedence is planned for v0.4.0; verify that the override release is published and loaded before relying on it.

Legacy `<fluid-account-messaging>` embeds use a separate versioned classic script. They also need an override-capable release and a selector matching that legacy element. Do not load the classic script and the module loader together on the same page.

## Verify your theme

1. Open a system screen without overrides. Check its fonts and colors against the standard theme settings.
2. Change a mapped color in the builder and confirm the preview uses the new value. Save it and check the member page too.
3. With the override-capable runtime, add a primary/foreground override pair. Confirm those values take precedence while unmodified styles still follow the standard settings.
4. Change the theme variable referenced by the override and check the rendered result.
5. Remove the override and confirm the most recent attribute value becomes visible.
6. Check a dialog and, for Messaging, its tinted surfaces and focus states. Confirm that selected fonts actually load.
7. Check the builder preview and the signed-in member page separately.

## Troubleshooting

| Symptom                                          | What to check                                                                                                                     |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| Theme CSS does not beat the attribute            | Confirm the loaded runtime includes the override release. Check that the rule matches the element and loads in the same document. |
| A preset changes the page but not the screen     | Check the standard setting IDs, valid values, and whether an override intentionally takes precedence.                             |
| The font family is set but looks wrong           | Load the font in the theme layout and use its correct CSS family name.                                                            |
| Colors look invalid instead of falling back      | Inspect the computed public property for a defined value that is not a CSS color.                                                 |
| Changes appear live but not in the builder       | Ensure the preview iframe receives the same layout CSS and updated source variables.                                              |
| A pinned embed ignores the new override behavior | Upgrade it to a verified release containing the override support.                                                                 |