Theming @allxsmith/bestax-bulma

@allxsmith/bestax-bulma wraps Bulma 1.x, which is themed through --bulma-* CSS custom properties. Theme an app by overriding the right variables — no component re-styling required.

Approach

Recolor a brand color by overriding its hue/saturation/lightness trio — Bulma derives every shade, light/dark, and invert variant from --bulma-<color>-h / -s / -l. Override the trio and the whole palette follows.

Choose an override path:

• Theme component (runtime, preferred). Exported from the package. Pass named HSL props (primaryH, primaryS, primaryL, …) and/or bulmaVars={{ '--bulma-*': '…' }} for everything else. Add isRoot to inject the variables globally at :root (once, at the app root); omit it to scope the variables to the wrapped subtree.
• Plain CSS. Set :root { --bulma-primary-h: …; } (or any selector) directly.
• Build-time Sass. @use 'bulma/sass' with ($primary: #1e6b99) when compiling Bulma's Sass.

For dark mode, pass colorMode to Theme ('light' | 'dark' | 'system'). It writes Bulma's data-theme attribute on <html> (plus data-<prefix>theme inside a ConfigProvider with a classPrefix, which the prefixed flavors read), flipping the light/dark scheme — global, even on a scoped Theme; 'system' follows the OS prefers-color-scheme. Drive it from state on the app-root Theme: <Theme isRoot colorMode={mode}>.

Contrast rules (dark mode is on by default)

When nothing sets a data-theme attribute (omitting colorMode preserves an existing one, but apps that never configured it have none), Bulma follows the visitor's OS: --bulma-text, --bulma-scheme-main, etc. flip on a dark-mode machine even if the design never intended a dark theme. Custom fixed tokens (--my-canvas: #f6f4ec) do not flip — producing near-white Bulma text on the author's fixed light background. Apply exactly one of these rules whenever custom color tokens or fixed-color surfaces exist:

• Single-mode design → pin the scheme. <Theme isRoot colorMode="light"> (or "dark"), so an OS preference can never invert text out from under the fixed palette.
• Both modes → no exposed fixed tokens. Derive custom tokens from scheme variables (--my-canvas: var(--bulma-scheme-main)) — or flip them yourself under both dark-mode paths: [data-theme='dark'] and @media (prefers-color-scheme: dark) scoped to :root:not([data-theme]), since colorMode="system" removes the attribute (snippets in references/css-variables.md). Alternating/tinted section bands are first-class props: bgColor="scheme-main-bis" (then "scheme-main-ter") on Section (also Hero, Footer, Container, Box, Card) renders a scheme-tracking inline background — never bgColor="light": light/white/grey helper backgrounds are fixed colors that fight dark mode. Keep the derive-from-scheme-vars CSS for other custom surfaces. Theme bulmaVars now accepts --bulma-scheme-main/-bis/-ter (and the -invert trio) overrides, so one Theme re-tints every band at once.
• Fixed-color surface → fixed-color content. On a surface that never changes (a dark hero, a brand banner), pin the content's colors too: solid/filled buttons and explicit text colors, never scheme-derived defaults or thin outlines that depend on the flipping scheme.

Reach for the helper props (color / textColor / bgColor / colorShade, textSize, textWeight, fontFamily) to apply themed colors and type to individual components. Variant flags and value unions are component-specific — never carry one over by analogy: isLight exists on Button and Notification only (Tag has none, and LinkButtonProps omits it); Tag size is normal | medium | large (no small, unlike Button); Buttons has isCentered, Tags does not (center tags with justifyContent="center"); the verbatim truth table is references/themeable-components.md.

Quick start

import { Theme, Button } from '@allxsmith/bestax-bulma';

// Global brand theme at the app root.
<Theme isRoot primaryH="265" primaryS="65%" primaryL="55%">
  <App />
</Theme>;

// Themed components recolor automatically.
<Button color="primary">Save</Button>;

App-wide config (icons & class prefix)

ConfigProvider sets app-wide options once at the root, separate from Theme. Wrap the app so you don't repeat the same prop on every component:

import { ConfigProvider } from '@allxsmith/bestax-bulma';

// Set the icon library once — <Icon> no longer needs a `library` prop.
<ConfigProvider iconLibrary="fa">
  <App />
</ConfigProvider>;
// now <Icon name="check" /> resolves as Font Awesome; no per-icon library="fa".

• iconLibrary — 'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols'. Icon reads it (library || iconLibrary || 'fa'), so set it here instead of on each <Icon>.
• classPrefix — namespaces every Bulma class (e.g. bulma-) to avoid collisions with other CSS.

Nest Theme and ConfigProvider together at the root (order doesn't matter).

References

• references/css-variables.md — the --bulma-* variable map (colors, scheme/text/border, radius, fonts, sizes, weights, dark mode) and all three override mechanisms.
• references/themeable-components.md — which components take color/size props, the real accepted values, and the shared helper props.

Examples

• examples/theme-config.tsx — a custom brand theme at the app root, plus a scoped override.
• examples/dark-mode.tsx — a light/dark toggle using Bulma's data-theme (plus data-<prefix>theme inside a ConfigProvider with a classPrefix).

Checklist

• Recolor brand colors via the HSL trio (*-h / *-s / *-l), not by hard-coding hex on components.
• Apply a global theme once with <Theme isRoot> (or :root); use scoped <Theme> for one-off sections.
• Set non-color tokens (radius, fonts, sizes) through bulmaVars or :root; a custom --bulma-family-* needs its font actually loaded (index.html <link> or an @fontsource import).
• Implement dark mode with data-theme on <html> (plus data-<prefix>theme inside a ConfigProvider with a classPrefix, which the prefixed flavors read); do not expect a shipped dark-mode component.
• Pass color/textColor/bgColor (not custom CSS) to color individual components.
• Set the icon library once with <ConfigProvider iconLibrary="…"> at the root, not library on every <Icon>.