bestax-mcp 0.0.0

package/data/skills/bestax-migrate/references/unmappables.md

@@ -0,0 +1,124 @@
+# Recipes for every TODO(bestax-migrate) the codemod leaves
+
+Work through `grep -rn "TODO(bestax-migrate)" src/` with these. Delete each comment once
+the site is converted.
+
+## `unsupported-file` — `.astro` / `.vue` / `.svelte` / `.mdx` imports
+
+The codemod can't parse these formats, so files in them that import
+react-bulma-components are reported (not rewritten). Migrate them by hand: swap the
+import to `@allxsmith/bestax-bulma` and apply the same renames the component/prop maps
+describe — the mapping is identical, only the rewriting is manual.
+
+## `peer-deps` — install-blocking version conflicts
+
+Reported from package.json, not a code TODO. bestax-bulma's peers: **React ^18 || ^19**
+(upgrade react/react-dom before installing — RBC v4 also ran on 17) and optional
+**@fortawesome/fontawesome-free ^6.7 || ^7** (FA 5 apps: upgrade, or
+`npm install --legacy-peer-deps` and keep FA 5 for your own `<i>` tags).
+
+## `Element` — no generic element
+
+bestax has no `Element`. Pick the semantic component (`Block`, `Box`, `Content`, …) that
+matches the usage, or plain JSX with classes:
+
+```tsx
+// Before
+<Element renderAs="span" textColor="grey" m={2}>…</Element>
+// After
+<Span textColor="grey" m="2">…</Span>   // bestax exports Span/Paragraph/Strong/etc.
+```
+
+## `Tile` — Bulma v1 replaced tiles with Grid
+
+Convert ancestor/parent/child tile trees to `Grid`/`Cell` (docs:
+https://bestax.io/docs/api/grid/grid):
+
+```tsx
+// Before
+<Tile kind="ancestor"><Tile kind="parent" size={8}><Tile kind="child">A</Tile></Tile></Tile>
+// After
+<Grid><Cell colSpan={8}>A</Cell></Grid>
+```
+
+Match the old proportions with `Cell` span props; tiles' `vertical` becomes grid flow.
+
+## Controlled `Dropdown` (`value` / `onChange`, `Dropdown.Item value`)
+
+bestax `Dropdown` is compositional — you own the selection state:
+
+```tsx
+const [choice, setChoice] = useState('a');
+<Dropdown label={labels[choice]} closeOnClick>
+  <Dropdown.Item active={choice === 'a'} onClick={() => setChoice('a')}>
+    First
+  </Dropdown.Item>
+  <Dropdown.Item active={choice === 'b'} onClick={() => setChoice('b')}>
+    Second
+  </Dropdown.Item>
+</Dropdown>;
+```
+
+## `Pagination` extras (`delta`, `next`/`previous`, `showFirstLast`, `showPrevNext`, `autoHide`)
+
+bestax `Pagination` renders from `total`/`current`/`onPageChange` with its own windowing.
+Drop `delta` (built-in), render conditionally instead of `autoHide`
+(`{total > 1 && <Pagination …/>}`), and compose `Pagination.Previous`/`Pagination.Next`
+manually if custom labels are essential.
+
+## `Modal` (`closeOnEsc`, `closeOnBlur`, `showClose`)
+
+bestax `Modal` already closes on Esc and background click and shows the close button
+whenever `onClose` is set — usually just delete these props. To hide the close button,
+omit `onClose` and render your own close control.
+
+## `touch` / `untilWidescreen` / `untilFullhd` / `{ only: true }` breakpoints
+
+No bestax helper-prop variants exist. Use Bulma classes directly:
+`className="is-hidden-touch"`, `is-flex-tablet-only`, etc. (all still exist in Bulma v1).
+
+## Icon children the parser couldn't read
+
+bestax `Icon` renders from `name` + `library` (+ `variant` for Font Awesome styles):
+
+```tsx
+<Icon name="github" library="fa" variant="brands" ariaLabel="GitHub" />
+```
+
+For icon fonts other than Font Awesome/MDI, see the `bestax-icons` skill.
+
+## Dynamic values (`state={x}`, `textSize={n}`, `align={side}`, …)
+
+The codemod only rewrites literals. Convert the expression at its source, e.g.:
+
+```tsx
+// Before: <Button state={hovered ? 'hover' : undefined}>
+<Button isHovered={hovered}>
+// Before: <Block textSize={n}>
+<Block textSize={String(n) as '1' | '2' | '3' | '4' | '5' | '6' | '7'}>
+```
+
+## Button shade colors (`black-bis`, `grey-light`, …) and `isSelected`
+
+bestax `Button` colors are the semantic set + `text`/`ghost`. For shades use
+`bgColor`/`textColor` (they accept the full palette incl. shades), and replace
+`isSelected` with `className="is-selected"` inside grouped buttons.
+
+## `colorVariant` / Hero `gradient` / Hero `halfheight`
+
+- `colorVariant="light"` → `isLight` where supported (Button, Notification), otherwise a
+  shade: `bgColor="primary-90"`.
+- Bulma v1 removed `is-bold` hero gradients — delete `gradient` or restyle with CSS.
+- `halfheight` has no bestax size; use `size="medium"` or a CSS height.
+
+## `domRef`
+
+bestax components don't take `domRef`. Most don't forward refs either — attach the ref to
+a DOM element inside, or wrap the component in a `<div ref={…}>`.
+
+## Helper props dropped from plain-element replacements
+
+Where the codemod produced a plain element (`Form.Label` → `<label>`, `Breadcrumb.Item` →
+`<li>`, `Table.Container` fallback `<div>`), Bulma helper props were dropped with a TODO.
+Re-express them as classes: `m={2}` → `className="m-2"`, `textAlign="center"` →
+`className="has-text-centered"`.

package/data/skills/bestax-optimize/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: bestax-optimize
+description: Reduce the built CSS size of an app using @allxsmith/bestax-bulma — measure raw and gzip size, then apply the cheapest lever that fits (lighter prebuilt CSS flavor, hand-rolled modular Sass build, import and icon-asset hygiene). Use when the CSS bundle looks too big, a size budget or Lighthouse audit flags stylesheet weight, switching bestax.css to a versions/*.css flavor, or setting up a modular @use Bulma/Sass build.
+license: MIT
+---
+
+# Optimizing CSS size with @allxsmith/bestax-bulma
+
+The JS side is tree-shakable (the **entire** library is ~49 KB min+gzip). The stylesheet is
+not: a prebuilt flavor ships all of Bulma + the bestax extras regardless of which components
+the app renders. Judge stylesheet weight by the **gzipped** transfer size — never the raw
+`dist/` number.
+
+## Always measure first
+
+Run the production build, then measure the built CSS — raw and gzip:
+
+```sh
+npm run build
+wc -c dist/assets/*.css            # raw bytes (what Vite reports)
+gzip -c dist/assets/*.css | wc -c  # transfer bytes (what users download)
+```
+
+Re-measure after **every** step below and report the before/after delta (raw + gzip). Never
+claim a saving without a number.
+
+⚠️ **~800 KB raw is ~82 KB over the wire.** Seeing ~800 KB of CSS in `dist/` is expected
+with the default flavor, not a build misconfiguration — servers and CDNs gzip/brotli by
+default. If the gzip number is already within the app's budget, say so and stop: "your CSS is
+already fine" is a valid, honest outcome.
+
+## Decision flow
+
+Cheapest first. Use only the library's own shipped CSS builds and SCSS sources — do not add
+third-party build plugins (no CSS purgers/post-processors).
+
+1. **Flavor switch** — one-line import change, minutes (up to ~15 KB gzip).
+2. **Modular Sass build** — small `@use` file, the biggest honest win.
+3. **Import & icon-asset hygiene** — minor; JS and icon fonts, not the Bulma CSS.
+
+## Lever 1 — lighter prebuilt flavor
+
+Swap the single CSS import (in `src/main.tsx` / `src/main.jsx`) between the shipped flavors.
+Measured sizes drift slightly between releases — hence measure:
+
+| Flavor       | Import                                                               |    Raw |   Gzip |
+| ------------ | -------------------------------------------------------------------- | -----: | -----: |
+| complete     | `import '@allxsmith/bestax-bulma/bestax.css';`                       | ~800KB | ~82 KB |
+| no-dark-mode | `import '@allxsmith/bestax-bulma/versions/bestax-no-dark-mode.css';` | ~680KB | ~70 KB |
+| no-helpers   | `import '@allxsmith/bestax-bulma/versions/bestax-no-helpers.css';`   | ~595KB | ~67 KB |
+
+Prefixed variants (`versions/bestax-prefixed.css` ~875 KB/~84 KB,
+`versions/bestax-no-helpers-prefixed.css` ~655 KB/~69 KB) exist for CSS-collision
+**compatibility, not size** — a prefixed flavor must pair with
+`<ConfigProvider classPrefix="bestax-">` at the app root, and switching a non-prefixed app to
+one is never a size optimization.
+
+- `no-dark-mode` (~12 KB gzip saved) — only when the app pins a single color scheme (a fixed
+  `Theme colorMode` / `data-theme`).
+- `no-helpers` (~15 KB gzip saved) — **hard gate below**.
+
+⚠️ **The `no-helpers` gate: check for helper props first.** That flavor drops every class the
+helper props compile to — components still render, but the props silently do nothing. Before
+recommending it, grep the app's source for helper props on bestax components:
+
+- spacing: `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my`, `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py`
+- color: `color`, `backgroundColor` (+ `colorShade`/`backgroundColorShade`), `textColor`, `bgColor`
+- typography: `textSize`, `textAlign`, `textTransform`, `textWeight`, `fontFamily`
+- display/visibility: `display`, `visibility` (+ `displayMobile`…`visibilityFullhd` viewport variants)
+- flexbox: `flexDirection`, `flexWrap`, `justifyContent`, `alignContent`, `alignItems`, `alignSelf`, `flexGrow`, `flexShrink`
+- misc: `float`, `overflow`, `overlay`, `interaction`, `cursor`, `radius`, `shadow`, `skeleton`, `clearfix`, `relative`, `fullHeight`
+
+…and for raw Bulma helper classes in `className` strings (`is-*`, `has-*`, `m*-*`, `p*-*`,
+`is-size-*`, `is-hidden*`, `is-flex*`). **Any hit → do not use `no-helpers`**; fall back to
+`no-dark-mode` or Lever 2. The bestax extras helpers (`is-cursor-*`, sizing) are dropped too.
+
+## Lever 2 — modular Sass build
+
+Compile only the Bulma modules + bestax extras partials the app actually uses. Needs the
+`sass` compiler as a dev dependency (Bulma's own build tool — Vite compiles `.scss` natively):
+
+```sh
+npm install -D sass
+```
+
+Create `src/styles.scss` — base + themes always come first:
+
+```scss
+// Configure shared variables FIRST (before anything loads utilities) —
+// the prebuilt flavors set this brand primary; omit it and buttons revert
+// to Bulma's default turquoise:
+@use 'bulma/sass/utilities' with (
+  $primary: #1e6b99
+);
+
+// Required base: reset + CSS variable definitions
+@use 'bulma/sass/base';
+@use 'bulma/sass/themes';
+
+// One line per stock Bulma component the app imports…
+@use 'bulma/sass/elements/button';
+@use 'bulma/sass/components/navbar';
+// …and per bestax extras component:
+@use '@allxsmith/bestax-bulma/scss/components/dialog';
+// Helper categories only if the app uses those helper props:
+@use 'bulma/sass/helpers/spacing';
+```
+
+Then replace the prebuilt CSS import in `src/main.tsx` with `import './styles.scss';`,
+build, and measure. Derive the `@use` list from the components the app imports from
+`@allxsmith/bestax-bulma` — the full component→partial mapping, the authoritative extras
+partial inventory, and a worked example are in `references/modular-build.md`.
+
+## Lever 3 — import & icon-asset hygiene (minor)
+
+- **Named imports.** `import * as Bestax from '@allxsmith/bestax-bulma'` defeats tree
+  shaking. Convert to named imports (`import { Button, Card } from …`) — a JS-side saving
+  (whole library ≈ 49 KB min+gzip), so report it honestly as minor.
+- **Unused icon libraries.** Scaffolded apps may carry an icon library the app never uses:
+  icon-font packages in `package.json` (`@fortawesome/fontawesome-free`, `@mdi/font`,
+  `material-icons`, `material-symbols`) with their CSS imports in `src/main.*`, or Ionicons
+  CDN `<script>` tags in `index.html`. Icon fonts often outweigh Bulma itself — if no
+  `<Icon>` uses that library, delete the dependency/import/script. Pure win, no tooling.
+
+## References
+
+- `references/modular-build.md` — full Lever 2 procedure: component→partial mapping, the
+  authoritative extras partial inventory, helper categories, and a worked `styles.scss`.
+- Docs: [Optimizing CSS Size](https://bestax.io/docs/guides/getting-started/optimizing-css) ·
+  [Modular — Option C](https://bestax.io/docs/guides/getting-started/modular#option-c--hand-rolled-modular-scss-advanced) ·
+  [CSS Variations](https://bestax.io/docs/guides/getting-started/variations#file-size-comparison)

package/data/skills/bestax-optimize/references/modular-build.md

@@ -0,0 +1,173 @@
+# Modular Sass build — component→partial mapping and procedure
+
+Build a stylesheet containing only what the app uses, from the library's own SCSS sources.
+This is the "Option C" pattern from the
+[Modular guide](https://bestax.io/docs/guides/getting-started/modular#option-c--hand-rolled-modular-scss-advanced).
+
+## Prerequisites
+
+```sh
+npm install -D sass
+```
+
+`sass` is Bulma's own compiler, dev-only. Vite compiles `.scss` out of the box — no plugin.
+`bulma` is already present as a dependency of `@allxsmith/bestax-bulma`, and the library
+publishes its SCSS sources (`src/scss` ships in the npm package, exposed via the
+`@allxsmith/bestax-bulma/scss/*` export).
+
+## The required base — always first
+
+```scss
+// Configure shared variables FIRST — a Sass module can only be configured on
+// its first load, and every Bulma module loads utilities internally. The
+// prebuilt bestax flavors set this brand primary; omit it and is-primary
+// reverts to Bulma's default turquoise (verified failure mode).
+@use 'bulma/sass/utilities' with (
+  $primary: #1e6b99
+);
+
+// Required: reset + CSS variable definitions
+@use 'bulma/sass/base';
+@use 'bulma/sass/themes';
+```
+
+- `base` — minireset, generic element styles, keyframes.
+- `themes` — registers the `--bulma-*` custom properties (colors, radii, schemes) and
+  light/dark setup. Without it, components render unstyled-looking because every color
+  resolves to nothing.
+- Exception: `bulma/sass/grid/columns` and `bulma/sass/grid/grid` register their own CSS
+  vars and can technically stand alone — include base + themes anyway; it is the safe
+  default.
+
+## Component → partial mapping
+
+**Rule:** stock Bulma components map to `bulma/sass/<category>/<lowercased-name>`; bestax
+extras map to `@allxsmith/bestax-bulma/scss/<category>/<lowercased-name>`. Components that
+are pure stock Bulma (Button, Box, Card, Navbar, Modal, Hero, …) have **no** extras partial —
+Bulma's own module is all they need.
+
+Stock Bulma examples:
+
+```scss
+@use 'bulma/sass/elements/button'; // Button, Buttons
+@use 'bulma/sass/elements/box'; // Box
+@use 'bulma/sass/elements/notification'; // Notification
+@use 'bulma/sass/elements/title'; // Title, SubTitle
+@use 'bulma/sass/form/input'; // Input
+@use 'bulma/sass/form/select'; // Select
+@use 'bulma/sass/components/card'; // Card
+@use 'bulma/sass/components/modal'; // Modal
+@use 'bulma/sass/components/navbar'; // Navbar
+@use 'bulma/sass/grid/columns'; // Columns, Column
+@use 'bulma/sass/grid/grid'; // Grid, Cell
+@use 'bulma/sass/layout/container'; // Container
+@use 'bulma/sass/layout/section'; // Section
+```
+
+## Authoritative bestax extras inventory
+
+Every extras partial that exists (from the library's `src/scss/**/_index.scss` — this list
+is **more complete** than the docs page's Option C example, which omits several):
+
+**Components** (`@allxsmith/bestax-bulma/scss/components/<name>`):
+`loading`, `collapse`, `tooltip`, `steps`, `sidebar`, `toast`, `dialog`, `carousel`, `tabs`,
+`reveal`, `avatar`, `avatars`, `badge`
+
+**Form** (`@allxsmith/bestax-bulma/scss/form/<name>`):
+`checkbox`, `radio`, `switch`, `slider`, `numberinput`, `rate`, `autocomplete`, `taginput`,
+`picker-popover`, `dateinput`, `timeinput`, `datetimeinput`
+
+**Elements** (`@allxsmith/bestax-bulma/scss/elements/<name>`): `linkbutton`
+
+**Helpers** (`@allxsmith/bestax-bulma/scss/helpers/<name>`): `cursor`, `sizing`
+
+Notes:
+
+- The extras partial name is the component name lowercased (`Dialog` →
+  `scss/components/dialog`; `NumberInput` → `scss/form/numberinput`).
+- Extras `Tabs` **extends** stock Bulma tabs (vertical variant) — an app using `Tabs` needs
+  both `bulma/sass/components/tabs` and `@allxsmith/bestax-bulma/scss/components/tabs`.
+- `DateInput`/`TimeInput`/`DateTimeInput` also need `picker-popover`.
+- Stock-Bulma form controls still need their Bulma module (`bulma/sass/form/…`); the extras
+  form partials above style only the bestax-specific behavior.
+- Bulma component modules pull their own internal sub-elements — e.g.
+  `elements/notification` styles its `delete` close button itself (verified). No extra
+  `@use` lines are needed for pieces rendered _inside_ a component you've already included.
+
+## Bulma helper categories
+
+Include a helper module **only if the app's helper props (or `className` strings) need it**:
+
+⚠️ The `display` prop (`display="flex"`, `is-flex`, `is-block`, …) lives in **`visibility`**,
+not `flexbox` — `flexbox` holds only the alignment props. Verified failure mode: omit
+`visibility` and every `display="flex"` silently renders `block`.
+
+```scss
+@use 'bulma/sass/helpers/spacing'; // m*/p* props
+@use 'bulma/sass/helpers/color'; // color/backgroundColor props, has-text-*/has-background-*
+@use 'bulma/sass/helpers/typography'; // textSize/textAlign/textTransform/textWeight/fontFamily
+@use 'bulma/sass/helpers/visibility'; // display/visibility props incl. display="flex" (is-flex/is-block/is-hidden*)
+@use 'bulma/sass/helpers/flexbox'; // flex* alignment props (justifyContent/alignItems/flexGrow…) — NOT display="flex"
+@use 'bulma/sass/helpers/other'; // overlay/interaction/radius/shadow/clearfix/relative…
+```
+
+## Procedure
+
+1. **Inventory** — list every component the app imports from `@allxsmith/bestax-bulma`
+   (grep the import statements; remember re-exports through local files).
+2. **Map** — one `@use` line per component via the rule above; add the helper categories the
+   app's helper props require; dedupe.
+3. **Write `src/styles.scss`** — the `utilities` config first, then base + themes, then the
+   mapped lines.
+4. **Swap the import** — in `src/main.tsx`/`src/main.jsx`, replace the prebuilt CSS import
+   (`bestax.css` or `versions/*.css`) with `import './styles.scss';`.
+5. **Build and measure** — raw + gzip, compare against the prebuilt baseline, report the
+   delta.
+6. **Verify visually** — open the app; a missing partial shows up as an unstyled component,
+   an omitted helper module as ignored spacing/color props. Add the missing `@use` line —
+   never paper over it with custom CSS.
+
+## Worked example — the create-bestax starter app
+
+The `npm create bestax` starter renders `Container`, `Section`, `Columns`/`Column`, `Image`,
+`Title`/`SubTitle`, `Box`, `Card`, `Buttons`/`Button`, and `Notification` — all stock Bulma,
+no bestax extras. Its helper props are `display`/`justifyContent` (visibility + flexbox),
+`textAlign` (typography), and `textColor` (color); it uses no spacing props. That inventory
+compiles to the following — verified pixel-equivalent to the prebuilt `complete` flavor in
+headless Chromium (light and dark), at 453 KB raw / 40 KB gzip vs 813 KB / 83 KB:
+
+```scss
+// src/styles.scss
+@use 'bulma/sass/utilities' with (
+  $primary: #1e6b99
+);
+
+@use 'bulma/sass/base';
+@use 'bulma/sass/themes';
+
+@use 'bulma/sass/elements/box';
+@use 'bulma/sass/elements/button'; // Button + Buttons
+@use 'bulma/sass/elements/image';
+@use 'bulma/sass/elements/notification';
+@use 'bulma/sass/elements/title'; // Title + SubTitle
+@use 'bulma/sass/components/card';
+@use 'bulma/sass/grid/columns';
+@use 'bulma/sass/layout/container';
+@use 'bulma/sass/layout/section';
+
+@use 'bulma/sass/helpers/visibility'; // display="flex"
+@use 'bulma/sass/helpers/flexbox'; // justifyContent/flexGrow/flexShrink
+@use 'bulma/sass/helpers/typography'; // textAlign
+@use 'bulma/sass/helpers/color'; // textColor
+```
+
+```tsx
+// src/main.tsx — before
+import '@allxsmith/bestax-bulma/bestax.css';
+// after
+import './styles.scss';
+```
+
+A custom class prefix is `$class-prefix` in the same `with (…)` block as `$primary`, paired
+with `<ConfigProvider classPrefix="my-">` at the app root (the library's own
+`src/scss/versions/*.scss` flavor builds use exactly this mechanism).

package/data/skills/bestax-theming/SKILL.md

@@ -0,0 +1,117 @@
+---
+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.
+license: MIT
+---
+
+# 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>`, 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 this case:
+  `background: var(--bulma-scheme-main-bis)` (then `-ter`), never `bgColor="light"` —
+  `light`/`white`/grey helper backgrounds are fixed colors that fight dark mode.
+- **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
+
+```tsx
+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:
+
+```tsx
+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`.
+
+## 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>`; 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>`.

package/data/skills/bestax-theming/examples/dark-mode.tsx

@@ -0,0 +1,38 @@
+// Dark mode for an app built on @allxsmith/bestax-bulma.
+//
+// The Theme component drives the light/dark scheme: pass `colorMode` and it
+// writes Bulma's `data-theme` attribute on <html>. This is global (even on a
+// scoped Theme); `'system'` removes the attribute so Bulma follows the OS
+// `prefers-color-scheme`. Wrap the app once at the root.
+import React, { useState } from 'react';
+import {
+  Theme,
+  Box,
+  Button,
+  Title,
+  Notification,
+} from '@allxsmith/bestax-bulma';
+
+type Mode = 'light' | 'dark' | 'system';
+
+export function DarkModeToggle() {
+  const [mode, setMode] = useState<Mode>('system');
+
+  return (
+    <Theme isRoot colorMode={mode}>
+      <Box>
+        <Title size="5">Color mode: {mode}</Title>
+        <Notification color="info">
+          Components below follow the current Bulma color scheme.
+        </Notification>
+        <Button color="primary" onClick={() => setMode('light')}>
+          Light
+        </Button>
+        <Button color="primary" onClick={() => setMode('dark')}>
+          Dark
+        </Button>
+        <Button onClick={() => setMode('system')}>System</Button>
+      </Box>
+    </Theme>
+  );
+}

package/data/skills/bestax-theming/examples/theme-config.tsx

@@ -0,0 +1,60 @@
+// Custom brand theme for an app built on @allxsmith/bestax-bulma.
+// Copy this to your app and adjust the HSL values to your brand.
+//
+// Bulma 1.x derives every shade of a color from its hue/saturation/lightness
+// trio (--bulma-<color>-h / -s / -l), so overriding the trio recolors the whole
+// palette. The <Theme> component writes those CSS variables for you:
+//   - isRoot          -> inject the variables globally at :root (use once, at the app root)
+//   - without isRoot  -> wrap children in a <div> and scope the variables to it
+import React from 'react';
+import {
+  Theme,
+  Button,
+  Notification,
+  Box,
+  Title,
+} from '@allxsmith/bestax-bulma';
+
+// 1) Global brand theme at the app root.
+//    Hue is unitless; saturation and lightness are percentages.
+export function ThemedApp({ children }: { children: React.ReactNode }) {
+  return (
+    <Theme
+      isRoot
+      // Brand primary (HSL trio) — recolors every `is-primary` / `has-text-primary`.
+      primaryH="265"
+      primaryS="65%"
+      primaryL="55%"
+      // A matching link color.
+      linkH="200"
+      linkS="80%"
+      linkL="45%"
+      // Anything without a named prop goes through `bulmaVars`, keyed by the real
+      // --bulma-* variable names (string values).
+      bulmaVars={{
+        '--bulma-radius': '0.75rem',
+        '--bulma-radius-large': '1.25rem',
+        // 'Inter' must actually be loaded (index.html <link> or an @fontsource
+        // import) — declaring the family var alone falls back to system-ui.
+        '--bulma-family-primary': "'Inter', system-ui, sans-serif",
+      }}
+    >
+      {children}
+    </Theme>
+  );
+}
+
+// 2) Scoped override — theme just one section; the rest of the app is untouched.
+export function PromoPanel() {
+  return (
+    <Theme primaryH="16" primaryS="85%" primaryL="55%">
+      <Box>
+        <Title size="4">Limited offer</Title>
+        <Notification color="primary">
+          This panel uses a warm primary; the rest of the app is unaffected.
+        </Notification>
+        <Button color="primary">Claim it</Button>
+      </Box>
+    </Theme>
+  );
+}