Bestax Bulma 主题定制

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install bestax-theming
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 bestax-theming。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Bestax Bulma 主题定制可帮助开发者通过覆盖 Bulma 1.x CSS 自定义属性，而不是逐个重新设置组件样式，来定制使用 @allxsmith/bestax-bulma 构建的应用。通过色相、饱和度和亮度变量设置品牌调色板，调整字体和间距令牌，并通过组件辅助属性应用颜色。
该技能介绍了使用 Theme 进行运行时主题设置、直接覆盖 CSS 以及构建时 Sass 配置。还涵盖了可靠的浅色和深色模式行为，包括避免固定颜色表面与依赖配色方案的文本相遇时产生对比度问题。借助 ConfigProvider，开发者可以在应用根部一次性配置图标库并为 Bulma 类设置命名空间前缀。Openclaw Skills 让这些工作流程更容易在整个应用中准确应用。

应用场景

建立或更新全应用品牌调色板，无需添加一次性的组件样式。
将主题应用于特定部分，同时保持应用其余部分不变。
添加浅色、深色或跟随操作系统的颜色模式，并避免对比度不足。
自定义 Bulma 的圆角、字体、字号、字重及其他设计令牌。
color
、
textColor
、
bgColor
fontFamily
等组件属性，一致地应用视觉样式。
全局配置 Font Awesome、Material Design Icons、Ionicons 或其他受支持的图标库。
添加类名前缀，减少与其他样式表发生 CSS 命名冲突的风险。

工作原理

确定所需范围：在根部设置全应用样式，或在某个子树周围设置局部覆盖。
选择覆盖机制：使用 Theme 组件进行运行时配置，使用普通 CSS 直接覆盖自定义属性，或在构建时配置 Bulma Sass。
覆盖相关的 --bulma--h、--bulma--s 和 --bulma--l 值来设置品牌颜色，使 Bulma 能够生成调色板变体。
通过 Theme 的 colorMode 属性配置深色模式行为。选择 light、dark 或 system；该组件会控制 上的 Bulma data-theme 属性。
在两种配色方案下检查自定义表面和令牌。固定为单一模式设计；从配色方案变量派生双模式表面；或者明确将固定颜色的内容与其固定颜色的背景配对。
使用受支持的辅助属性设置组件级颜色和字体，并遵循各组件实际支持的属性值和变体。
使用 ConfigProvider 包装应用，一次性设置共享的图标库和类名前缀选项。

配置指南

使用项目的包管理器安装 @allxsmith/bestax-bulma，然后导入所需的组件和提供程序。该技能不指定包安装命令，也不提供包清单；请根据你的环境参阅该包的安装文档。
添加根主题，并在需要时添加全应用配置：
import { ConfigProvider, Theme } from '@allxsmith/bestax-bulma';
;
使用 isRoot 在 :root 中全局注入主题变量。如果主题只应应用于所包装的子树，请省略它。colorMode 接受 light、dark 或 system；system 会跟随操作系统偏好。可以按任意顺序在根部嵌套 Theme 和 ConfigProvider。
如需直接通过 CSS 设置主题，请在 :root 或其他选择器中定义相关的 --bulma-* 属性。如需在构建时自定义 Sass，请使用 @use 'bulma/sass' with (...) 配置 Bulma。如果自定义 --bulma-family-* 字体令牌，请确保通过 HTML

• 或 @fontsource 导入加载字体本身。 Bestax Bulma 主题定制 数据架构与分类体系
  此技能介绍的是配置和源文件，而非生成的数据存储。主题值通过 React 属性或 CSS 自定义属性提供。
  配置区域 位置或机制 示例
  品牌调色板 Theme 属性或 --bulma-* CSS 变量 primaryH、primaryS、primaryL；--bulma-primary-h
  其他 Bulma 令牌 Theme 的 bulmaVars、CSS 或 Sass 配色方案颜色、文本、边框、圆角、字体、字号和字重
  主题范围 Theme 组件 isRoot 用于全局变量；省略则限定于子树
  颜色模式 根部的 Theme 和 HTML data-theme 属性 light、dark 或 system
  全应用选项 ConfigProvider iconLibrary、classPrefix
  参考资料 references/ css-variables.md、themeable-components.md
  示例实现 examples/ theme-config.tsx、dark-mode.tsx
  文档所述工作流程不会自动生成任何文件或元数据。让自定义双模式表面与 Bulma 配色方案变量保持一致；或者当 :root 没有 data-theme 属性时，为 [data-theme='dark'] 和系统偏好路径分别定义明确的样式。

高级特性

全调色板颜色派生：
更改某种颜色的色相、饱和度和亮度三元组，使 Bulma 能够生成相关色阶和变体。
作用域化运行时主题：
使用嵌套或局部的
Theme
实例进行子树级覆盖；使用
isRoot
作为单一全局注入点。
适配系统的深色模式：
colorMode="system"
以跟随
prefers-color-scheme
；请注意，此模式会移除
data-theme
属性。
适配配色方案的表面：
Section
、
Hero
、
Footer
、
Container
、
Box
Card
等组件的
bgColor
scheme-main-bis
scheme-main-ter
等受支持的值。
集中调整配色方案色调：
Theme
bulmaVars
覆盖受支持的配色方案变量，包括
scheme-main
系列及其反转变体。
全局图标和 CSS 配置：
ConfigProvider
一次性设置
iconLibrary
classPrefix
，无需重复传入图标库属性，也可避免类名冲突风险。
确保组件特定配置准确：
references/themeable-components.md
了解可接受的属性值；各组件的标志和联合类型各不相同，因此不要假定某个组件支持的属性也适用于其他组件。
实现参考资料：
references/css-variables.md
了解变量映射和覆盖方法，并参阅随附的主题配置和深色模式示例。

name: bestax-theming description: Customize colors, branding, dark mode, and visual tokens of an app built with @allxsmith/bestax-bulma. Use when changing the primary/brand color, recoloring components, overriding Bulma --bulma-* CSS variables, setting fonts/radius/spacing tokens, adding light/dark mode, or configuring the app-wide icon library / class prefix via ConfigProvider.

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--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 , 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: .

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. (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.

;

// Themed components recolor automatically.
Save;

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 — no longer needs a library prop.

;
// now 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 .
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.

Checklist

Recolor brand colors via the HSL trio (*-h / *-s / -l), not by hard-coding hex on components.
Apply a global theme once with (or :root); use scoped 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

• or an @fontsource import). Implement dark mode with data-theme on ; 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 at the root, not library on every .

Bestax CSS Size Optimizer

AgentScope Gemini 用量修复