## Flow Theming (CSS variables)

Flow forms are rendered inside a Shadow DOM and use the Mantine UI library for styling.  You can customise their appearance via three mechanisms:

- set **primaryColor** and **primaryShade** in the Form block inspector,
- define your own colour palettes in the **Colours** field,
- paste custom CSS into the **Theme Overrides** textarea.

Theme Overrides are injected into the form’s shadow root (`.smartcloud-flow-shadow-root`).  Use them to override Mantine variables such as `--mantine-spacing-md` or `--mantine-radius-md`, or Flow‑specific wizard tokens like `--flow-wizard-gap` and `--flow-wizard-number-active-bg`.

Flow also exposes a broader non-wizard token layer for the regular form blocks, so clients can restyle inputs, choice controls, sliders, ratings, PIN fields, fieldsets, collapse toggles and action buttons without depending on Mantine internals.

For the richer display/content blocks, Flow also exposes dedicated `--flow-*` tokens for blockquotes, marks/highlights, badges, code blocks, number formatting, spoilers, images and overflow-list items.

Flow Modal and Flow Gallery live outside the shadow root, so they are themed from ordinary page CSS instead of the form-level Theme Overrides textarea. Useful light-DOM tokens include:

- modal shell: `--wps-flow-modal-panel-background`, `--wps-flow-modal-content-background`, `--wps-flow-modal-panel-color`, `--wps-flow-modal-panel-shadow`, `--wps-flow-modal-backdrop-background`
- modal chrome: `--wps-flow-modal-chrome-background`, `--wps-flow-modal-chrome-color`
- gallery: `--wps-flow-gallery-stage-background`, `--wps-flow-gallery-nav-background`, `--wps-flow-gallery-nav-color`, `--wps-flow-gallery-meta-color`

The modal slot wrappers for header/body/actions are intentionally transparent. If you want one continuous modal surface that will not cover sticky header/footer layers or the close button, theme `.wps-flow-modal__content` through `--wps-flow-modal-content-background`. The top-right chrome wrapper stays transparent; `--wps-flow-modal-chrome-background` and `--wps-flow-modal-chrome-color` are used by the individual close/fullscreen buttons so they remain legible over dark media while still reading as separate controls.

```css
.wps-flow-modal {
  --wps-flow-modal-panel-background: #ffffff;
  --wps-flow-modal-content-background: #ffffff;
  --wps-flow-modal-panel-color: #0f172a;
  --wps-flow-modal-chrome-background: #ffffff;
  --wps-flow-modal-chrome-color: #0f172a;
}

.wps-flow-gallery {
  --wps-flow-gallery-stage-background: #0f172a;
  --wps-flow-gallery-nav-background: rgba(15, 23, 42, 0.82);
  --wps-flow-gallery-nav-color: #ffffff;
  --wps-flow-gallery-meta-color: #e2e8f0;
}
```

For example:

```css
.smartcloud-flow-shadow-root {
  --mantine-radius-md: 6px;
  --mantine-spacing-md: 1rem;
  --mantine-color-blue-6: #0ea5e9;

  --flow-control-radius: 999px;
  --flow-control-border-color: var(--mantine-color-blue-3);
  --flow-submit-bg: var(--mantine-color-blue-filled);
  --flow-submit-color: white;
  --flow-fieldset-border: 1px solid var(--mantine-color-blue-2);
}

.flow-wizard-step-number {
  --flow-wizard-number-size: 40px;
  --flow-wizard-number-active-bg: var(--mantine-color-green-6);
  --flow-wizard-number-active-color: white;
}

.flow-block__pin {
  --flow-pin-input-size: 3rem;
}

.flow-block__collapse {
  --flow-collapse-toggle-radius: 999px;
}

.flow-block__display-blockquote {
  --flow-blockquote-accent: var(--mantine-color-blue-6);
  --flow-blockquote-bg: color-mix(
    in srgb,
    var(--mantine-color-blue-6) 10%,
    white
  );
}

.flow-block__display-badge {
  --flow-badge-padding: 0.4rem 0.85rem;
}

.flow-block__table {
  --flow-table-header-bg: color-mix(in srgb, #0f172a 6%, white);
}

.flow-block__timeline {
  --flow-timeline-accent: var(--mantine-color-blue-6);
}
```

Important Flow-specific tokens include:

- General fields: `--flow-field-gap`, `--flow-field-padding`, `--flow-field-radius`, `--flow-field-bg`, `--flow-field-border`, `--flow-field-shadow`.
- Labels and messages: `--flow-field-label-color`, `--flow-field-label-size`, `--flow-field-label-weight`, `--flow-field-description-color`, `--flow-field-description-size`, `--flow-field-error-color`, `--flow-field-error-size`, `--flow-field-caption-color`, `--flow-field-caption-size`.
- Input-like controls: `--flow-control-min-height`, `--flow-control-radius`, `--flow-control-bg`, `--flow-control-border-width`, `--flow-control-border-color`, `--flow-control-color`, `--flow-control-placeholder-color`, `--flow-control-padding-inline`, `--flow-control-padding-block`, `--flow-control-focus-border-color`, `--flow-control-focus-shadow`, `--flow-control-disabled-opacity`.
- Choice controls: `--flow-choice-size`, `--flow-choice-color`, `--flow-choice-label-color`.
- Sliders: `--flow-slider-track-size`, `--flow-slider-track-bg`, `--flow-slider-bar-color`, `--flow-slider-thumb-size`, `--flow-slider-thumb-bg`, `--flow-slider-thumb-border`.
- PIN and rating: `--flow-pin-gap`, `--flow-pin-input-size`, `--flow-rating-size`, `--flow-rating-active-color`, `--flow-rating-inactive-color`.
- Fieldsets and collapse: `--flow-fieldset-border`, `--flow-fieldset-radius`, `--flow-fieldset-padding`, `--flow-fieldset-legend-color`, `--flow-collapse-toggle-bg`, `--flow-collapse-toggle-border`, `--flow-collapse-toggle-radius`, `--flow-collapse-toggle-padding`, `--flow-collapse-toggle-color`.
- Action buttons: `--flow-action-button-radius`, `--flow-action-button-padding`, `--flow-submit-bg`, `--flow-submit-color`, `--flow-submit-border`, `--flow-save-draft-bg`, `--flow-save-draft-color`, `--flow-save-draft-border`.
- Display/content blocks: `--flow-display-text-color`, `--flow-display-text-weight`, `--flow-display-text-line-height`, `--flow-display-title-color`, `--flow-display-title-weight`, `--flow-display-title-line-height`, `--flow-display-title-letter-spacing`, `--flow-blockquote-bg`, `--flow-blockquote-accent`, `--flow-blockquote-color`, `--flow-blockquote-radius`, `--flow-blockquote-padding`, `--flow-blockquote-gap`, `--flow-blockquote-border-width`, `--flow-blockquote-icon-size`, `--flow-blockquote-text-style`, `--flow-blockquote-cite-color`, `--flow-blockquote-cite-size`, `--flow-mark-bg`, `--flow-mark-color`, `--flow-mark-radius`, `--flow-mark-padding`, `--flow-highlight-bg`, `--flow-highlight-color`, `--flow-highlight-radius`, `--flow-highlight-padding`, `--flow-badge-padding`, `--flow-badge-circle-padding`, `--flow-badge-font-size`, `--flow-badge-font-weight`, `--flow-badge-letter-spacing`, `--flow-badge-text-transform`, `--flow-code-inline-bg`, `--flow-code-inline-color`, `--flow-code-block-bg`, `--flow-code-block-color`, `--flow-code-radius`, `--flow-code-padding`, `--flow-code-block-padding`, `--flow-number-color`, `--flow-number-weight`, `--flow-number-font-variant`, `--flow-spoiler-toggle-color`, `--flow-spoiler-content-color`, `--flow-image-radius`, `--flow-image-caption-color`, `--flow-image-caption-size`, `--flow-list-color`, `--flow-list-marker-color`, `--flow-list-padding-start`, `--flow-list-item-gap`, `--flow-table-color`, `--flow-table-border-color`, `--flow-table-cell-border-color`, `--flow-table-striped-bg`, `--flow-table-header-bg`, `--flow-table-header-color`, `--flow-table-header-weight`, `--flow-table-cell-color`, `--flow-table-caption-color`, `--flow-table-caption-padding-bottom`, `--flow-table-cell-padding-inline`, `--flow-table-cell-padding-block`, `--flow-timeline-color`, `--flow-timeline-gap`, `--flow-timeline-item-gap`, `--flow-timeline-content-gap`, `--flow-timeline-accent`, `--flow-timeline-line-opacity`, `--flow-timeline-bullet-color`, `--flow-timeline-bullet-weight`, `--flow-timeline-title-color`, `--flow-timeline-title-weight`, `--flow-overflow-item-bg`, `--flow-overflow-item-border`, `--flow-overflow-item-color`, `--flow-overflow-item-gap`, `--flow-overflow-item-radius`, `--flow-overflow-item-padding`, `--flow-overflow-item-shadow`, `--flow-overflow-summary-cursor`, `--flow-overflow-summary-font-weight`, `--flow-overflow-summary-letter-spacing`.
- AI suggestions: `--flow-ai-suggestions-border-thickness`, `--flow-ai-suggestions-border-stops`, `--flow-ai-suggestions-border-speed`.
- Submission metadata: `--flow-submission-meta-bg`, `--flow-submission-meta-border`, `--flow-submission-meta-radius`, `--flow-submission-meta-padding`, `--flow-submission-meta-gap`, `--flow-submission-meta-label-color`, `--flow-submission-meta-value-color`, `--flow-submission-meta-value-font`, `--flow-submission-meta-copy-bg`, `--flow-submission-meta-copy-border`, `--flow-submission-meta-copy-color`, `--flow-submission-meta-shadow`.

These tokens act as theme defaults; per-block editor settings can still take precedence when a block explicitly sets its own colour, size or radius.
- Container: `--flow-wizard-gap`, `--flow-wizard-border-radius`, `--flow-wizard-padding`.
- Header: `--flow-wizard-header-spacing`, `--flow-wizard-title-color`, `--flow-wizard-title-size`, `--flow-wizard-title-weight`.
- Progress: `--flow-wizard-progress-margin`, `--flow-wizard-bar-height`, `--flow-wizard-bar-color`, `--flow-wizard-bar-bg`.
- Stepper: `--flow-wizard-stepper-gap`, `--flow-wizard-numbers-gap`, `--flow-wizard-number-size`, `--flow-wizard-number-active-bg`, `--flow-wizard-number-inactive-bg`, `--flow-wizard-number-active-color`, `--flow-wizard-number-inactive-color`.
- Step content: `--flow-wizard-step-gap`, `--flow-wizard-step-padding`, `--flow-wizard-step-title-color`, `--flow-wizard-step-title-size`, `--flow-wizard-step-title-weight`, `--flow-wizard-step-desc-color`, `--flow-wizard-step-desc-size`, `--flow-wizard-fields-gap`.
- Controls: `--flow-wizard-controls-gap`, `--flow-wizard-controls-margin`, `--flow-wizard-controls-padding`, `--flow-wizard-controls-border-top`.
- Buttons: `--flow-wizard-prev-color`, `--flow-wizard-prev-bg`, `--flow-wizard-prev-border`, `--flow-wizard-next-color`, `--flow-wizard-next-bg`.

For a full reference of Mantine CSS variables see the Mantine documentation.

Useful selectors when you want to scope overrides to a specific block type:

- `.flow-block__text`, `.flow-block__textarea`, `.flow-block__select`, `.flow-block__number`, `.flow-block__password`, `.flow-block__date`
- `.flow-block__checkbox`, `.flow-block__radio`, `.flow-block__switch`
- `.flow-block__pin`, `.flow-block__slider`, `.flow-block__rangeslider`, `.flow-block__rating`, `.flow-block__file`, `.flow-block__tags`
- `.flow-block__fieldset`, `.flow-block__collapse`, `.flow-block__submit`, `.flow-block__save-draft`
- `.flow-block__display-text`, `.flow-block__display-title`, `.flow-block__display-blockquote`, `.flow-block__display-mark`, `.flow-block__display-highlight`, `.flow-block__display-badge`, `.flow-block__display-code`, `.flow-block__display-number-formatter`, `.flow-block__display-spoiler`, `.flow-block__display-image`, `.flow-block__list`, `.flow-block__list-item`, `.flow-block__table`, `.flow-block__table-row`, `.flow-block__table-th`, `.flow-block__table-td`, `.flow-block__timeline`, `.flow-block__timeline-item`, `.flow-block__overflow-list`, `.flow-block__overflow-list-item`
- `.flow-ai-suggestions`, `.flow-ai-suggestions-border`, `.flow-submission-meta`

These `.flow-block__*` wrappers are the stable theming surface. The interactive Mantine control or button often lives one level deeper and consumes the `--flow-*` token there, so prefer setting tokens on the wrapper instead of targeting internal helper classes.

Success-state layouts usually reuse the action-button and submission-meta styling surfaces, so most confirmation-screen theming can be handled through those tokens instead of a separate success-state token set.

### Copy-paste recipes

These snippets are designed for quick client handoff.  Paste one into the Theme Overrides field, then swap the colours and font family as needed.

#### Rounded SaaS

```css
.smartcloud-flow-shadow-root {
  --mantine-font-family: Inter, system-ui, sans-serif;
  --mantine-radius-md: 14px;
  --mantine-color-blue-6: #2563eb;
  --mantine-primary-color-filled: var(--mantine-color-blue-filled);

  --flow-control-radius: 14px;
  --flow-control-border-color: var(--mantine-color-blue-2);
  --flow-control-focus-border-color: var(--mantine-color-blue-5);
  --flow-control-focus-shadow: 0 0 0 3px rgb(37 99 235 / 0.12);

  --flow-submit-bg: linear-gradient(135deg, #2563eb, #1d4ed8);
  --flow-submit-color: white;
  --flow-wizard-number-active-bg: #2563eb;
}
```

#### Clinical Minimal

```css
.smartcloud-flow-shadow-root {
  --flow-control-radius: 6px;
  --flow-control-bg: #ffffff;
  --flow-control-border-color: #cbd5e1;
  --flow-control-focus-border-color: #0f172a;
  --flow-control-focus-shadow: 0 0 0 1px #0f172a;

  --flow-field-description-color: #475569;
  --flow-fieldset-border: 1px solid #cbd5e1;
  --flow-submit-bg: #0f172a;
  --flow-submit-color: #ffffff;
}
```

#### Bold Brand

```css
.smartcloud-flow-shadow-root {
  --mantine-font-family: "Space Grotesk", system-ui, sans-serif;
  --mantine-color-pink-6: #e11d48;
  --mantine-primary-color-filled: var(--mantine-color-pink-filled);

  --flow-control-border-width: 2px;
  --flow-control-border-color: #fecdd3;
  --flow-choice-color: #e11d48;
  --flow-submit-bg: #e11d48;
  --flow-submit-color: #ffffff;
  --flow-wizard-next-bg: #e11d48;
}
```

#### Dark Contrast

```css
.smartcloud-flow-shadow-root[data-mantine-color-scheme="dark"] {
  --flow-control-bg: #111827;
  --flow-control-color: #f8fafc;
  --flow-control-border-color: #334155;
  --flow-control-focus-border-color: #38bdf8;

  --flow-fieldset-border: 1px solid #334155;
  --flow-submit-bg: #38bdf8;
  --flow-submit-color: #0f172a;
  --flow-wizard-next-bg: #38bdf8;
  --flow-wizard-next-color: #0f172a;
}
```