Theming Guide

Overview

Bonzai 2 uses CSS Custom Properties (CSS Variables) for theming, enabling instant color changes without waiting for CDN propagation. The Theme Manager web part provides an in-page interface for configuring:

• Core Colors — Primary, Background, Text, Accent
• Mega Menu Branding — colors, logo, nav/dropdown spacing, breadcrumb, search bar, page layout fix
• Footer Branding — colors, logo, section titles, column separators, feedback section
• Slider Branding — overlay colors for the News / Highlights slider
• Navigation Source — one URL lets multiple sites share Mega Menu and Footer lists
• Style Options — dark mode, corner style (Sharp / Rounded / Pill)

Theme Manager vs Brick

CSS Custom Properties

All Bonzai 2 web parts read from CSS custom properties set on :root. Theme Manager writes these whenever the editor changes a value, and the shared theme loader re-applies them on every page load. The four Core Colors you pick drive 16+ derived values (hover states, tints, borders) — you don't set those manually.

Core (set by the four color pickers)

:root {
  /* Brand — derived from Primary */
  --bonzai-primary;
  --bonzai-primary-hover;
  --bonzai-primary-light;      /* 10% alpha of primary */

  /* Accent — derived from Accent */
  --bonzai-accent;
  --bonzai-accent-hover;
  --bonzai-accent-light;       /* 10% alpha of accent */

  /* Text — derived from Text */
  --bonzai-text-primary;
  --bonzai-text-secondary;
  --bonzai-text-tertiary;
  --bonzai-text-inverse;

  /* Background — derived from Background */
  --bonzai-bg-primary;
  --bonzai-bg-secondary;
  --bonzai-bg-tertiary;

  /* Border — derived based on light / dark mode */
  --bonzai-border-color;
  --bonzai-border-color-light;
  --bonzai-border-color-dark;

  /* Corner Style */
  --bonzai-border-radius-sm;   /* 0px sharp, 2px rounded, 8px  pill */
  --bonzai-border-radius-md;   /* 0px sharp, 4px rounded, 16px pill */
  --bonzai-border-radius-lg;   /* 0px sharp, 6px rounded, 24px pill */
}

Mega Menu Branding

:root {
  --bonzai-megamenu-bg;
  --bonzai-megamenu-bg-secondary;
  --bonzai-megamenu-bg-hover;
  --bonzai-megamenu-text;
  --bonzai-megamenu-text-secondary;
  --bonzai-megamenu-accent;
  --bonzai-megamenu-accent-hover;
  --bonzai-megamenu-accent-light;
  --bonzai-megamenu-hover-bg;
  --bonzai-megamenu-hover-text;
  --bonzai-megamenu-logo-url;               /* CSS url() or 'none' */
  --bonzai-megamenu-breadcrumb-display;     /* 'flex' or 'none' */
  --bonzai-megamenu-breadcrumb-justify;     /* flex-start | center | flex-end */
  --bonzai-megamenu-breadcrumb-offset;      /* 0%–40% */

  /* Navigation bar spacing (50–150% of base) */
  --bonzai-megamenu-nav-spacing-xs ... -xxl;

  /* Dropdown panel spacing (50–150% of base) */
  --bonzai-megamenu-dropdown-spacing-xs ... -xxl;
}

Footer Branding

:root {
  --bonzai-footer-bg;
  --bonzai-footer-bg-secondary;
  --bonzai-footer-text;
  --bonzai-footer-text-secondary;
  --bonzai-footer-link;
  --bonzai-footer-link-hover;
  --bonzai-footer-border;
  --bonzai-footer-logo-url;                 /* CSS url() or 'none' */
  --bonzai-footer-logo-width;               /* scales 50–200% */
  --bonzai-footer-logo-height;              /* scales 50–200% */
  --bonzai-footer-title-color;
  --bonzai-footer-title-font-weight;        /* 400 or 600 */
  --bonzai-footer-title-font-style;         /* normal or italic */
  --bonzai-footer-title-text-decoration;    /* none or underline */
  --bonzai-footer-title-font-size;          /* 10px–24px */
  --bonzai-footer-items-color;
  --bonzai-footer-separator-width;          /* 0px or 1px */
  --bonzai-footer-feedback-display;         /* 'block' or 'none' */
  --bonzai-footer-feedback-min-height;      /* 2–10 lines × 22px */
  --bonzai-footer-feedback-text-color;
}

Slider Branding

:root {
  --bonzai-slider-social-color;    /* comment & like icons (default #ffffff) */
  --bonzai-slider-overlay-text;    /* overlay titles, metadata, excerpts */
  --bonzai-slider-date-color;      /* date label */
}

Dark Mode

Dark Mode is a theme-level setting inside Theme Manager — it's not a per-user toggle that end users flip on each page. When the editor turns Dark Mode on and saves the theme, every user who loads a page after that sees the dark theme. When it's off, everyone sees the light theme.

• Toggle is in Theme Manager under Style Options → Dark Mode.
• When switched on, if Background/Text still look light-mode, Theme Manager auto-inverts them to #1f1f1f / #e5e5e5 as a sensible default. You can override either picker afterwards.
• Secondary/tertiary text and background are re-derived from the new Background color so web parts stay readable.
• The Dark Mode preset is just a shortcut that sets isDark = trueplus a pre-tuned dark palette — pick it, then tweak individual colors.

Persistence: localStorage + BonzaiTheme List

Theme Manager has two ways to remember a saved theme. Both run on the same Save Theme click; you don't choose — the property pane toggle decides.

1. Browser localStorage (always on) — key bonzai-theme-v2. Persists the theme for this browser only. Ideal while you're iterating; useless for other users, other devices, or sessions where storage is blocked (guest / private).
2. BonzaiTheme list (when persistToSite is on — the default) — a hidden list on the site with a single item and a ThemeJson column holding the serialized theme. The shared theme loader reads this on every page, so all users see the same theme. Theme Manager creates the list and column on the first save (this creation step typically requires Site Owner permissions).

Navigation Source (Multi-Site)

The Navigation Source Site URL field lets you keep a single set of Mega Menu and Footer lists on one site and have other sites read from it, instead of duplicating the lists on every sub-site.

• Leave empty (default) — Mega Menu and Footer read from the current site.
• Set to another https:// site URL — they read from that site instead.
• When you tab out of the field, Theme Manager validates the URL and checks whetherMegaMenuNavigation and FooterNavigation exist there (showing item counts or a not-found warning).
• The footer feedback form still submits to the FooterFeedback list on the current site — only the navigation list reads are redirected.
• Changing this value also changes which site's BonzaiTheme list is read/written (see Persistence above), so it is effectively a "central theming + navigation site" pointer.

Best Practices

Related Resources

• Theme Manager Web Part — Full property, slider, and color reference (every setting in the UI)
• Mega Menu Extension — Consumes the --bonzai-megamenu-* properties and reads MegaMenuNavigation from the current or source site
• Footer Extension — Consumes the --bonzai-footer-* properties and reads FooterNavigation / FooterFeedback
• Home Page Recipe — Setting up Theme Manager on your homepage
• Classic vs Modern — Migration considerations for theming