create-bestax 4.2.18 → 4.3.0

package/templates/skills/bestax-migrate/references/css-migration.md

@@ -26,11 +26,18 @@ choice below applies.
   **Visual note**: `bestax.css` ships with `$primary` set to bestax blue (`#1e6b99`),
   not Bulma's stock turquoise — `is-primary` surfaces (hero, navbar, buttons) change
   color. Keep the stock Bulma look with `--css bulma`, or set your own brand color via
-  `--bulma-primary-*` CSS variables / a Sass build. Set `--bulma-primary-invert-l` along with
-  `--bulma-primary-h`, `--bulma-primary-s` and `--bulma-primary-l`: it is the lightness of the
-  text on a primary surface, and bestax's build fixes it for its dark blue, so a light primary set
-  through the other three alone keeps white labels. To get stock Bulma's turquoise back on top of
-  `bestax.css`, copy those four from Bulma's own `bulma/css/bulma.css`.
+  `--bulma-primary-*` CSS variables / a Sass build. With the variables, set
+  `--bulma-primary-invert-l` and `--bulma-primary-on-scheme-l` along with `--bulma-primary-h`,
+  `--bulma-primary-s` and `--bulma-primary-l`. The first is the lightness of the label on a
+  primary surface and the second of primary text on the page, and bestax's build fixes both for
+  its dark blue, so a light primary set through the trio alone keeps white labels and pale text.
+  To get stock Bulma's turquoise back on top of `bestax.css`, copy those five from Bulma's own
+  `bulma/css/bulma.css`. The on-scheme lightness differs between its light and dark schemes, so
+  set each scheme's value where the app shows both; the `bestax-theming` skill's
+  `references/css-variables.md` ("The lightnesses Bulma's build picks for contrast") shows how,
+  and what reads each one. Text the page colors with `has-text-primary` converts to
+  `textColor="primary"`, which reads the trio's own lightness, under 2:1 on white for turquoise
+  (in stock Bulma too); add `colorShade="on-scheme"` to take the shade made for text.
 
 - **SCSS files**: Bulma 0.9's `@import 'bulma/bulma.sass'` (plus preceding
   `$var: value !default;` overrides) became Bulma v1 module syntax, with simple literal

package/templates/skills/bestax-migrate/references/rbx/prop-map.md

@@ -88,19 +88,25 @@ several of those narrow it to specific tags (`Footer` is `'footer' | 'div'`, `Co
 `'div' | 'p'`). The codemod passes `as` through only where bestax really accepts it, and TODOs it
 everywhere else:
 
-| bestax component             | `as` accepts               |
-| ---------------------------- | -------------------------- |
-| `Button`                     | any element type           |
-| `Title`, `SubTitle`          | `h1`–`h6`, `p`             |
-| `Image`                      | `'figure' \| 'div' \| 'p'` |
-| `Footer`                     | `'footer' \| 'div'`        |
-| `Media`                      | `'article' \| 'div'`       |
-| `Media.Left`                 | `'figure' \| 'div'`        |
-| `Level.Item`                 | `'div' \| 'p' \| 'a'`      |
-| `Control`                    | `'div' \| 'p'`             |
-| `Menu.Item`                  | any element type           |
-| `Dropdown.Item`              | `'a' \| 'div' \| 'button'` |
-| `Navbar.Item`, `Navbar.Link` | any element type           |
+| bestax component             | `as` accepts                                                                            |
+| ---------------------------- | --------------------------------------------------------------------------------------- |
+| `Button`                     | any element type                                                                        |
+| `Title`, `SubTitle`          | `h1`–`h6`, `p`                                                                          |
+| `Image`                      | `'figure' \| 'div' \| 'p'`                                                              |
+| `Footer`                     | `'footer' \| 'div'`                                                                     |
+| `Media`                      | `'article' \| 'div'`                                                                    |
+| `Media.Left`                 | `'figure' \| 'div'`                                                                     |
+| `Level.Item`                 | `'div' \| 'p' \| 'a'`                                                                   |
+| `Control`                    | `'div' \| 'p'`                                                                          |
+| `Menu.Item`                  | any element type                                                                        |
+| `Dropdown.Item`              | `'a' \| 'div' \| 'button'`                                                              |
+| `Navbar.Item`, `Navbar.Link` | any element type                                                                        |
+| `Container`                  | `'div' \| 'main' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer' \| 'nav'` |
+| `Hero`                       | `'section' \| 'div' \| 'main' \| 'header' \| 'footer' \| 'article' \| 'aside'`          |
+| `Hero.Head`                  | `'div' \| 'header' \| 'nav'`                                                            |
+| `Hero.Foot`                  | `'div' \| 'footer' \| 'nav'`                                                            |
+| `Panel`                      | `'nav' \| 'article' \| 'section' \| 'aside' \| 'div'`                                   |
+| `Panel.Block`                | `'a' \| 'div' \| 'label'`                                                               |
 
 Three traps worth naming, because rbx supplies `as` universally and the obvious guesses are
 wrong:
@@ -183,7 +189,7 @@ An existing `ref` is passed through untouched — which is safe only where the b
 one. rbx forwards a ref on every component; bestax does so on the form controls, plus `Avatar`,
 `Button`, `Carousel`, `CarouselItem`, `Dialog`, `Dropdown`, `EmptyState`, `Kbd`, `Kbd.Group`,
 `Link`, `LinkButton`, `Loader`, `Menu.Item`, `Modal`, `Navbar`, `Navbar.Burger`, `Navbar.Dropdown`,
-`Navbar.Item`, `Navbar.Link`, `SegmentedControl`, `SegmentedControl.Segment`, `Sidebar`, `Timeline`,
+`Navbar.Item`, `Navbar.Link`, `ScrollArea`, `SegmentedControl`, `SegmentedControl.Segment`, `Sidebar`, `Splitter`, `Splitter.Pane`, `Timeline`,
 `Timeline.Item`, `Toast`, `ToggleButton`, `TreeView` and `TreeView.Item`. "The form controls" there
 means the inputs themselves: the `Field`, `Field.Label`, `Field.Body`, `Checkboxes` and `Radios`
 wrappers around them forward nothing, and `Field` is a target this codemod emits.

package/templates/skills/bestax-migrate/references/react-bulma-components/prop-map.md

@@ -6,31 +6,36 @@ this automatically for literal values; dynamic values get TODOs.
 
 ## Renames and value changes
 
-| RBC                               | bestax                                                                                                                                                         |
-| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `renderAs`                        | `as` — **only** on polymorphic components (Button, Title/SubTitle, Footer, Level.Item, Media\*, Menu.Item, Navbar.Item/Link, Dropdown.Item); elsewhere flagged |
-| `domRef`                          | flagged — rename to `ref` on the components that forward one, else use a DOM child                                                                             |
-| `backgroundColor`                 | `bgColor`                                                                                                                                                      |
-| `textColor`                       | `textColor` (same)                                                                                                                                             |
-| `colorVariant`                    | flagged — use `isLight` or a color shade                                                                                                                       |
-| `textSize={4}`                    | `textSize="4"` (string union `'1'`–`'7'`)                                                                                                                      |
-| `textAlign="center"`              | `textAlign="centered"` (`justify`→`justified`)                                                                                                                 |
-| `textFamily`                      | `fontFamily`                                                                                                                                                   |
-| `italic`                          | `textTransform="italic"`                                                                                                                                       |
-| `m/mt/…/py={3}`                   | `m="3"` (string union `'0'`–`'6'`)                                                                                                                             |
-| `pull="right"`                    | `float="right"`                                                                                                                                                |
-| `marginless` / `paddingless`      | `m="0"` / `p="0"`                                                                                                                                              |
-| `clipped`                         | `overflow="clipped"`                                                                                                                                           |
-| `radiusless` / `shadowless`       | `radius="radiusless"` / `shadow="shadowless"`                                                                                                                  |
-| `unselectable`                    | `interaction="unselectable"`                                                                                                                                   |
-| `hidden` / `invisible` / `srOnly` | `visibility="hidden"` / `"invisible"` / `"sr-only"`                                                                                                            |
-| `display="hidden"`                | `visibility="hidden"`                                                                                                                                          |
-| `display="relative"`              | boolean `relative`                                                                                                                                             |
-| flexbox props                     | same names/values (`flexDirection`, `justifyContent`, …)                                                                                                       |
-| `clearfix`, `overlay`             | same                                                                                                                                                           |
+| RBC                               | bestax                                                                                                                    |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `renderAs`                        | `as` — **only** where bestax declares one ([listed below](#renderas--as-and-the-props-that-follow-it)); elsewhere flagged |
+| `domRef`                          | flagged — rename to `ref` on the components that forward one, else use a DOM child                                        |
+| `backgroundColor`                 | `bgColor`                                                                                                                 |
+| `textColor`                       | `textColor` (same)                                                                                                        |
+| `colorVariant`                    | flagged — use `isLight` or a color shade                                                                                  |
+| `textSize={4}`                    | `textSize="4"` (string union `'1'`–`'7'`)                                                                                 |
+| `textAlign="center"`              | `textAlign="centered"` (`justify`→`justified`)                                                                            |
+| `textFamily`                      | `fontFamily`                                                                                                              |
+| `italic`                          | `textTransform="italic"`                                                                                                  |
+| `m/mt/…/py={3}`                   | `m="3"` (string union `'0'`–`'6'`)                                                                                        |
+| `pull="right"`                    | `float="right"`                                                                                                           |
+| `marginless` / `paddingless`      | `m="0"` / `p="0"`                                                                                                         |
+| `clipped`                         | `overflow="clipped"`                                                                                                      |
+| `radiusless` / `shadowless`       | `radius="radiusless"` / `shadow="shadowless"`                                                                             |
+| `unselectable`                    | `interaction="unselectable"`                                                                                              |
+| `hidden` / `invisible` / `srOnly` | `visibility="hidden"` / `"invisible"` / `"sr-only"`                                                                       |
+| `display="hidden"`                | `visibility="hidden"`                                                                                                     |
+| `display="relative"`              | boolean `relative`                                                                                                        |
+| flexbox props                     | same names/values (`flexDirection`, `justifyContent`, …)                                                                  |
+| `clearfix`, `overlay`             | same                                                                                                                      |
 
 ## `renderAs` → `as`, and the props that follow it
 
+`renderAs` becomes `as` on the components bestax declares one on: `Button`, `Title` and
+`SubTitle` (from `Heading`), `Image`, `Form.Control`, `Footer`, `Level.Item`, `Media` and its
+`Item`s, `Menu.Item`, `Navbar.Item`, `Navbar.Link`, `Dropdown.Item`, `Container`, `Hero`,
+`Hero.Header`, `Hero.Footer`, `Panel` and `Panel.Block`. Everywhere else it is flagged.
+
 bestax gives an element the attributes of the tag `as` names, and several components narrow
 `as` to the tags Bulma's markup allows there (`Footer` is `'footer' | 'div'`, `Control` is
 `'div' | 'p'`, `Level.Item` is `'div' | 'p' | 'a'`). RBC's `renderAs` took any tag, so two

package/templates/skills/bestax-migrate/references/react-bulma-components/unmappables.md

@@ -132,7 +132,7 @@ bestax `Button` colors are the semantic set + `text`/`ghost`. For shades use
 ## `colorVariant` / Hero `gradient` / Hero `halfheight` (`prop:size`)
 
 - `colorVariant="light"` → `isLight` where supported (Button, Notification), otherwise a
-  shade: `bgColor="primary-90"`.
+  shade: `bgColor="primary" backgroundColorShade="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.
 
@@ -165,8 +165,8 @@ The same TODO marks a `Heading` that sets `size` and `textSize` both: drop `size
 bestax components don't take `domRef`, but many forward a plain `ref` — the form controls, plus
 `Avatar`, `Button`, `Carousel`, `CarouselItem`, `Dialog`, `Dropdown`, `EmptyState`, `Kbd`,
 `Kbd.Group`, `Link`, `LinkButton`, `Loader`, `Menu.Item`, `Modal`, `Navbar`, `Navbar.Burger`,
-`Navbar.Dropdown`, `Navbar.Item`, `Navbar.Link`, `SegmentedControl`, `SegmentedControl.Segment`,
-`Sidebar`, `Timeline`, `Timeline.Item`, `Toast`, `ToggleButton`, `TreeView` and `TreeView.Item`. On
+`Navbar.Dropdown`, `Navbar.Item`, `Navbar.Link`, `ScrollArea`, `SegmentedControl`, `SegmentedControl.Segment`,
+`Sidebar`, `Splitter`, `Splitter.Pane`, `Timeline`, `Timeline.Item`, `Toast`, `ToggleButton`, `TreeView` and `TreeView.Item`. On
 those, rename `domRef` to `ref` and it works; do not restructure the markup. "The form controls"
 means the inputs themselves: the `Field`, `Field.Label`, `Field.Body`, `Checkboxes` and `Radios`
 wrappers around them forward nothing, and `Field` is a target this codemod emits.

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

@@ -49,6 +49,11 @@ extras map to `@allxsmith/bestax-bulma/scss/<category>/<lowercased-name>`. Compo
 are pure stock Bulma (Button, Box, Card, Navbar, Modal, Hero, …) have **no** extras partial —
 Bulma's own module is all they need.
 
+Bulma groups its form controls, so their modules don't follow the name: `Input` and `TextArea`
+are `bulma/sass/form/input-textarea`, `Checkbox`, `Checkboxes`, `Radio` and `Radios` are
+`bulma/sass/form/checkbox-radio`, and `Field` and `Control` are `bulma/sass/form/tools`.
+`Select` and `File` follow the rule.
+
 Stock Bulma examples:
 
 ```scss
@@ -56,8 +61,9 @@ Stock Bulma examples:
 @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/input-textarea'; // Input, TextArea
 @use 'bulma/sass/form/select'; // Select
+@use 'bulma/sass/form/tools'; // Field, Control
 @use 'bulma/sass/components/card'; // Card
 @use 'bulma/sass/components/modal'; // Modal
 @use 'bulma/sass/components/navbar'; // Navbar
@@ -74,12 +80,15 @@ is **more complete** than the docs page's Option C example, which omits several)
 
 **Components** (`@allxsmith/bestax-bulma/scss/components/<name>`):
 `loading`, `collapse`, `tooltip`, `popover`, `hovercard`, `contextmenu`, `steps`, `sidebar`,
-`toast`, `dialog`, `carousel`, `tabs`, `reveal`, `avatar`, `avatars`, `badge`, `emptystate`,
-`timeline`, `treeview`
+`toast`, `dialog`, `carousel`, `tabs`, `menu`, `reveal`, `avatar`, `avatars`, `badge`,
+`emptystate`, `timeline`, `treeview`, `scrollarea`
+
+**Layout** (`@allxsmith/bestax-bulma/scss/layout/<name>`): `splitter`
 
 **Form** (`@allxsmith/bestax-bulma/scss/form/<name>`):
-`checkbox`, `radio`, `switch`, `slider`, `numberinput`, `rate`, `autocomplete`, `taginput`,
-`picker-popover`, `dateinput`, `timeinput`, `datetimeinput`, `daterangeinput`
+`checkbox`, `radio`, `switch`, `slider`, `numberinput`, `pininput`, `rate`, `autocomplete`,
+`combobox`, `taginput`, `picker-popover`, `dateinput`, `timeinput`, `datetimeinput`,
+`daterangeinput`, `file`
 
 **Elements** (`@allxsmith/bestax-bulma/scss/elements/<name>`): `kbd`, `linkbutton`, `loader`,
 `notification`, `progress`, `skeleton`
@@ -90,29 +99,62 @@ 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`.
+- Sass names a `@use` after the last part of its URL and refuses two with the same name in one
+  file. A partial that extends a stock component often shares that name with the component's
+  Bulma module (`components/tabs`, `elements/notification`), so give the bestax line a name of
+  its own with `as`, the way the notes below do. The name changes nothing in the compiled CSS.
+- Extras `Tabs` **extends** stock Bulma tabs (vertical variant), so an app using `Tabs` needs
+  both:
+
+  ```scss
+  @use 'bulma/sass/components/tabs';
+  @use '@allxsmith/bestax-bulma/scss/components/tabs' as bestax-tabs;
+  ```
+
+- The `menu` partial **extends** stock Bulma menu (it draws `Menu.Section`'s heading and chevron,
+  and keeps the active item marked in forced colors, Windows' contrast themes), so an app using
+  `Menu` needs both, in either order:
+
+  ```scss
+  @use 'bulma/sass/components/menu';
+  @use '@allxsmith/bestax-bulma/scss/components/menu' as bestax-menu;
+  ```
+
+- The `file` partial **extends** stock Bulma file (File's keyboard focus ring, and the rounded
+  corners of a boxed `hasName` File with no name to show), so an app using `File` needs both, in
+  either order:
+
+  ```scss
+  @use 'bulma/sass/form/file';
+  @use '@allxsmith/bestax-bulma/scss/form/file' as bestax-file;
+  ```
+
 - `DateInput`/`TimeInput`/`DateTimeInput` also need `picker-popover`.
 - `DateRangeInput` needs `daterangeinput` for its field and `dateinput` for its calendar, and
   `picker-popover` too.
+- `PinInput`'s boxes are Bulma inputs, so an app using it needs `bulma/sass/form/input-textarea`
+  next to `scss/form/pininput`, and `bulma/sass/form/tools` for the label and help text around it.
 - `Popover.Close` renders a Bulma button, so an app using it needs `bulma/sass/elements/button`
   next to `scss/components/popover`.
 - `ContextMenu`'s menu is Bulma's dropdown markup, so an app using it needs
   `bulma/sass/components/dropdown` next to `scss/components/contextmenu`.
 - `Loader` is stock Bulma styled by `bulma/sass/elements/loader`, and the `isLoading`
   spinners on `Button`, `Control` and `Select` are Bulma's too. The `loader` extras partial
-  stops all of them under `prefers-reduced-motion: reduce` and keeps each ring open in forced
-  colors (Windows' contrast themes), so include it next to the Bulma modules in any build that
-  shows one. Its rules are `!important`, so the order of the two
-  `@use` lines does not matter.
+  stops all of them under `prefers-reduced-motion: reduce`, hides everything inside a loading
+  button where Bulma hides only the label, and keeps each ring open in forced colors (Windows'
+  contrast themes), so include it (`as bestax-loader`) next to the Bulma modules in any build
+  that shows one. Its
+  rules win over Bulma's either way, so the order of the two `@use` lines does not matter.
 - `Progress` and the skeletons are stock Bulma too (`bulma/sass/elements/progress`,
-  `bulma/sass/base/skeleton`). The `progress` and `skeleton` extras partials stop the
-  indeterminate bar's sweep and the skeleton pulse (`Skeleton`, the `skeleton` prop,
-  `hasSkeleton`) under `prefers-reduced-motion: reduce`, the same way and in either order.
+  `bulma/sass/base/skeleton`). The `progress` and `skeleton` extras partials
+  (`as bestax-progress`, `as bestax-skeleton`) stop the indeterminate bar's sweep and the
+  skeleton pulse (`Skeleton`, the `skeleton` prop, `hasSkeleton`) under
+  `prefers-reduced-motion: reduce`, the same way and in either order.
 - `Notification` is stock Bulma too (`bulma/sass/elements/notification`). The `notification`
   extras partial pads the end of one with a close button (`hasDelete`, or a `Delete` passed in)
-  so its text clears the button, so include it next to the Bulma module in any build that shows
-  a dismissible notification. It doesn't depend on the order of the two `@use` lines either.
+  so its text clears the button, so include it (`as bestax-notification`) next to the Bulma
+  module in any build that shows a dismissible notification. It doesn't depend on the order of
+  the two `@use` lines either.
 - 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.
@@ -194,7 +236,7 @@ Scaffolded with an icon library, the starter also needs `bulma/sass/elements/ico
 @use 'bulma/sass/helpers/flexbox'; // flexGrow
 @use 'bulma/sass/helpers/typography'; // textAlign
 
-@use '@allxsmith/bestax-bulma/scss/elements/notification'; // text clears the close button
+@use '@allxsmith/bestax-bulma/scss/elements/notification' as bestax-notification; // text clears the close button
 ```
 
 ```tsx

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

@@ -11,9 +11,15 @@ properties. Theme an app by overriding the right variables — no component re-s
 
 ## 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.
+Recolor a brand color by overriding its **hue/saturation/lightness trio**
+(`--bulma-<color>-h` / `-s` / `-l`). The color itself follows all three. Its shades and variants
+follow the hue and saturation, at lightnesses the trio doesn't set. Among those, the stylesheet's
+build picked the label on a solid color (`--bulma-<color>-invert-l`) and the color's text on the
+page (`--bulma-<color>-on-scheme-l`, which for `link` is every link) for contrast with the color
+it was built with, so when the new color reads lighter or darker than the built one, set them as
+well, or labels and text lose their contrast. `Theme`'s `bulmaVars` takes both, and on an
+`isRoot` `Theme` the on-scheme one takes a value per scheme, `{ light, dark }`
+(`references/css-variables.md`, "Colors").
 
 Choose an override path:
 
@@ -31,7 +37,12 @@ For **dark mode**, pass `colorMode` to `Theme` (`'light' | 'dark' | 'system'`).
 `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}>`.
+`Theme`: `<Theme isRoot colorMode={mode}>`. `Theme` writes the attribute, and an `isRoot` Theme's
+variables, before the browser paints what it rendered, but the page can paint before the app's
+script runs at all, so the scheme of that first frame comes from `index.html`: `data-theme` on
+the `<html>` for a scheme that never changes, or an inline `<head>` script that writes the
+visitor's saved choice for a toggle (`examples/dark-mode.tsx`). A server render includes neither,
+so a server-rendered page sets what it needs from its first paint in `index.html` and CSS.
 
 ## Contrast rules (dark mode is on by default)
 
@@ -42,8 +53,10 @@ theme. Custom fixed tokens (`--my-canvas: #f6f4ec`) do **not** flip — producin
 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.
+- **Single-mode design → pin the scheme on `<html>`.** `<html lang="en" data-theme="light">` (or
+  `"dark"`) in `index.html`, so the first paint has it and an OS preference can never invert text
+  out from under the fixed palette. `<Theme isRoot colorMode="light">` alone sets it only once
+  the app's script runs, and the page can show the OS scheme before that.
 - **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
@@ -113,13 +126,14 @@ Nest `Theme` and `ConfigProvider` together at the root (order doesn't matter).
 ## 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`).
+- `examples/dark-mode.tsx` — a light/dark toggle that keeps the visitor's choice, with the `index.html` script that writes Bulma's `data-theme` from it before the first paint.
 
 ## Checklist
 
-- [ ] Recolor brand colors via the HSL trio (`*-h` / `*-s` / `*-l`), not by hard-coding hex on components.
+- [ ] Recolor brand colors via the HSL trio (`*-h` / `*-s` / `*-l`), not by hard-coding hex on components. A color that reads lighter or darker than the built one also sets `*-invert-l` and `*-on-scheme-l`, through `Theme bulmaVars` (the on-scheme one per scheme, on an `isRoot` Theme) or CSS.
 - [ ] 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.
+- [ ] Set the first paint's scheme in `index.html`: on `<html>` for a fixed scheme, from an inline `<head>` script for a saved choice.
 - [ ] 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/templates/skills/bestax-theming/examples/dark-mode.tsx

@@ -1,38 +1,121 @@
-// Dark mode for an app built on @allxsmith/bestax-bulma.
+// A light/dark toggle for an app built on @allxsmith/bestax-bulma that keeps
+// the visitor's choice.
 //
-// The Theme component drives the light/dark scheme: pass `colorMode` and it
-// writes Bulma's `data-theme` attribute on <html>, plus `data-<prefix>theme`
-// under a ConfigProvider `classPrefix`, which the prefixed flavors read. This
-// is global (even on a scoped Theme); `'system'` removes the attributes so
-// Bulma follows the OS `prefers-color-scheme`. Wrap the app once at the root.
+// Bulma reads the scheme from `data-theme` on <html>. `Theme colorMode` writes
+// that attribute before the browser paints what the app rendered, but only
+// once the app's script runs, and the page can paint before that, so on its
+// own it can show the OS scheme for a frame and then flip. The scheme for
+// that first frame comes from a script in index.html, which writes the saved
+// choice, or else the OS preference, before anything renders. Put it inside
+// <head> as a plain inline script, not `type="module"`, so it runs before the
+// body renders:
+//
+//   <script>
+//     // Bulma's scheme on <html> before the first paint: the saved choice,
+//     // or else the OS preference. The app saves under the same key.
+//     (() => {
+//       let saved = null;
+//       try {
+//         saved = localStorage.getItem('theme');
+//       } catch {
+//         // Storage is blocked, so fall back to the OS preference.
+//       }
+//       const dark =
+//         saved === 'light' || saved === 'dark'
+//           ? saved === 'dark'
+//           : window.matchMedia('(prefers-color-scheme: dark)').matches;
+//       document.documentElement.setAttribute(
+//         'data-theme',
+//         dark ? 'dark' : 'light'
+//       );
+//     })();
+//   </script>
+//
+// This file is the app's side: it starts from the attribute the script wrote,
+// passes its state to `Theme colorMode`, which keeps the attribute in step
+// with the toggle, and saves each choice under the key the script reads.
+// Under a ConfigProvider `classPrefix`, colorMode also writes
+// `data-<prefix>theme`, which the prefixed flavors read, so the script writes
+// that attribute too.
 import { useState } from 'react';
 import {
   Theme,
   Box,
-  Button,
   Title,
   Notification,
+  ToggleButton,
 } from '@allxsmith/bestax-bulma';
 
-type Mode = 'light' | 'dark' | 'system';
+export type ColorMode = 'light' | 'dark';
+
+/** The key the index.html script reads the saved choice from. */
+const STORAGE_KEY = 'theme';
+
+const isColorMode = (value: unknown): value is ColorMode =>
+  value === 'light' || value === 'dark';
+
+function savedColorMode(): ColorMode | null {
+  try {
+    const saved = localStorage.getItem(STORAGE_KEY);
+    return isColorMode(saved) ? saved : null;
+  } catch {
+    // A browser can block storage, in a private window or an embedded
+    // preview.
+    return null;
+  }
+}
+
+/**
+ * The scheme the index.html script wrote. Without the script, the same
+ * choice: the saved one, or the OS preference.
+ *
+ * `useState` calls this during render, and a server render has no document,
+ * so there it is 'light' and the browser's own render starts from the
+ * attribute.
+ */
+export function initialColorMode(): ColorMode {
+  if (typeof document === 'undefined') return 'light';
+  const written = document.documentElement.getAttribute('data-theme');
+  if (isColorMode(written)) return written;
+  return (
+    savedColorMode() ??
+    (window.matchMedia('(prefers-color-scheme: dark)').matches
+      ? 'dark'
+      : 'light')
+  );
+}
+
+/** Remember the visitor's choice for their next visit. */
+export function saveColorMode(mode: ColorMode) {
+  try {
+    localStorage.setItem(STORAGE_KEY, mode);
+  } catch {
+    // Storage is blocked, so the choice lasts until the page reloads.
+  }
+}
 
 export function DarkModeToggle() {
-  const [mode, setMode] = useState<Mode>('system');
+  const [mode, setMode] = useState<ColorMode>(initialColorMode);
+
+  const setDark = (dark: boolean) => {
+    const next = dark ? 'dark' : 'light';
+    setMode(next);
+    saveColorMode(next);
+  };
 
   return (
+    // Wrap the app once, at its root.
     <Theme isRoot colorMode={mode}>
       <Box>
-        <Title size="5">Color mode: {mode}</Title>
+        <Title size="5">Color scheme</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>
+        {/* One setting and its state: the label stays "Dark mode", and
+            ToggleButton says whether it is on through aria-pressed. */}
+        <ToggleButton pressed={mode === 'dark'} onPressedChange={setDark}>
+          Dark mode
+        </ToggleButton>
       </Box>
     </Theme>
   );

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

@@ -1,11 +1,21 @@
 // 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:
+// Bulma 1.x builds each color from a hue/saturation/lightness trio
+// (--bulma-<color>-h / -s / -l). Overriding the trio recolors the color
+// itself, and its shades and variants take the new hue and saturation at the
+// lightnesses the stylesheet was built with.
+// 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
+//
+// Of those built lightnesses, the label on a solid color
+// (--bulma-<color>-invert-l) and the color's text on the page
+// (--bulma-<color>-on-scheme-l, which for `link` is every link) were picked
+// for contrast with the stylesheet's own color. A color that reads lighter or
+// darker than that one sets them too, through bulmaVars. On an isRoot Theme
+// the on-scheme one takes a value for each scheme. references/css-variables.md
+// ("Colors") says how to pick them.
 import type { ReactNode } from 'react';
 import {
   Theme,
@@ -25,13 +35,15 @@ export function ThemedApp({ children }: { children: ReactNode }) {
       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={{
+        // Purple text reads darker than the stylesheet's blue at the same
+        // lightness, so on a dark page it needs a lighter shade than the one
+        // built for the blue. Each scheme gets its own, and these read at 4.5:1
+        // or more on Bulma's white and near-black pages. The white label the
+        // blue was built with still reads on this purple, so the invert stays.
+        '--bulma-primary-on-scheme-l': { light: '41%', dark: '65%' },
         '--bulma-radius': '0.75rem',
         '--bulma-radius-large': '1.25rem',
         // 'Inter' must actually be loaded (index.html <link> or an @fontsource
@@ -47,7 +59,7 @@ export function ThemedApp({ children }: { children: ReactNode }) {
 // 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%">
+    <Theme primaryH="16" primaryS="85%" primaryL="40%">
       <Box>
         <Title size="4">Limited offer</Title>
         <Notification color="primary">