create-bestax 4.2.18 → 4.2.19

package/templates/skills/bestax-theming/references/css-variables.md

@@ -67,9 +67,8 @@ If compiling Bulma's Sass yourself, set the SCSS variables before the CSS variab
 
 ## Colors — override the H/S/L trio to recolor
 
-Bulma derives a color's entire palette (shades, light/dark/invert variants) from three channels.
-Override the trio; the rest follows automatically. For each color `<c>` ∈ `primary`, `link`,
-`info`, `success`, `warning`, `danger`:
+Each color is three channels. For each color `<c>` ∈ `primary`, `link`, `info`, `success`,
+`warning`, `danger`:
 
 | Variable        | Meaning                    | `Theme` prop             |
 | --------------- | -------------------------- | ------------------------ |
@@ -77,9 +76,80 @@ Override the trio; the rest follows automatically. For each color `<c>` ∈ `pri
 | `--bulma-<c>-s` | saturation (`%`)           | `<c>S`                   |
 | `--bulma-<c>-l` | lightness (`%`)            | `<c>L`                   |
 
-Read-only derived values (set automatically; reference if you need them): `--bulma-<c>` (the
-resolved color), `--bulma-<c>-invert`, `--bulma-<c>-light`, `--bulma-<c>-dark`, `--bulma-<c>-rgb`,
-and numeric shades `--bulma-<c>-00` … `--bulma-<c>-95`.
+What a runtime trio moves: `--bulma-<c>`, the color itself, follows all three channels. Its
+shades, its light and dark variants, and its invert and on-scheme colors follow the hue and
+saturation, each at a lightness Bulma's Sass build wrote into the stylesheet for the color it was
+given:
+
+- the numeric shades `--bulma-<c>-00` … `--bulma-<c>-100` sit on a ramp of lightnesses
+  (`--bulma-<c>-<n>-l`) laid out from the built color's own, and `--bulma-<c>-light` and
+  `--bulma-<c>-dark` point into it. A new `-l` moves none of them, so a shade is as light as it
+  was before; only a Sass build lays the ramp out from a new color.
+- `--bulma-<c>-invert` and `--bulma-<c>-on-scheme` take the lightnesses below, which the build
+  picked for contrast.
+
+`--bulma-<c>-rgb` is the built color written out as a value, so it follows none of the trio.
+
+### The lightnesses Bulma's build picks for contrast
+
+The build picks the label and text lightnesses for each color by their contrast with the color it
+was given. A trio set at runtime leaves them as they were, so when a new color reads lighter or
+darker than the built one, which a change of hue or saturation can do as well as a change of
+lightness, set them too:
+
+| Variable                  | What reads it                                                                                                                |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `--bulma-<c>-invert-l`    | the label on a solid `<c>` surface: `Button`, `Tag` and `Notification` with `color="<c>"`, a colored `Hero` or `Navbar`, …   |
+| `--bulma-<c>-on-scheme-l` | `<c>` text on the page: `textColor="<c>" colorShade="on-scheme"`, a colored `Message`'s body, a field's colored help text, … |
+
+For `link`, the on-scheme lightness is also every link on the page (`--bulma-link-text`), so a new
+link color that reads lighter than Bulma's own leaves the page's links pale.
+
+bestax's stylesheet builds its primary from a dark blue, so the primary's invert is white
+(`var(--bulma-primary-100-l)`). A light primary set through the trio alone keeps those white
+labels: on stock Bulma's turquoise they read at under 2:1. Its on-scheme lightness was picked for
+the blue too, and is too light for turquoise text on a white page. The other colors are built
+from Bulma's own defaults. For a page made for stock Bulma, the bestax-migrate skill's
+`references/css-migration.md` covers getting its turquoise back.
+
+`Theme` doesn't set either one, so set them in your CSS, loaded after the library's styles:
+
+- **The invert** is one value for both schemes. Point it at a shade that reads on the new color: a
+  near-black `var(--bulma-<c>-05-l)` on a light color, a near-white `var(--bulma-<c>-100-l)` on a
+  dark one.
+- **The on-scheme lightness** has to read on the page's background, so Bulma gives each scheme
+  its own. A value on `:root` in your stylesheet wins in both, so give dark mode its own value on
+  both of its paths, as below.
+
+```css
+/* Stock Bulma's turquoise, with the values from bulma/css/bulma.css. */
+:root {
+  --bulma-primary-h: 171deg;
+  --bulma-primary-s: 100%;
+  --bulma-primary-l: 41%;
+  --bulma-primary-invert-l: var(--bulma-primary-05-l);
+  --bulma-primary-on-scheme-l: 21%;
+}
+[data-theme='dark'] {
+  --bulma-primary-on-scheme-l: 41%;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) {
+    --bulma-primary-on-scheme-l: 41%;
+  }
+}
+```
+
+For a color of your own, pick each value by its contrast (4.5:1 or more for text), or build
+Bulma's Sass with the color (`@use 'bulma/sass' with ($primary: …)`), which computes both.
+
+`textColor="<c>"` alone renders `has-text-<c>`, which reads the trio's own lightness, so text in a
+light color on a light page takes `colorShade="on-scheme"` as well.
+
+The build pairs each numbered shade, and the light and dark variants, with a label shade the same
+way (`--bulma-<c>-<n>-invert-l`, `--bulma-<c>-light-invert-l`, `--bulma-<c>-dark-invert-l`),
+picked for the hue and saturation it was given. After a change of hue, check the contrast of text
+you put on a numbered shade.
 
 ## Scheme, text, background, border (light/dark surfaces)
 
@@ -178,6 +248,9 @@ lone class or the `style` prop cannot outrank:
   its own declaration — target the declaring element in your CSS:
   `.tooltip-content { --bulma-tooltip-background: … }`.
 
+The `style` prop also misses on Checkbox and Radio, which put it on their hidden `<input>`; set
+their variables through `className` (see their entries below).
+
 ### Avatar / Avatars / Badge
 
 | Variable                                                          | Default                          |
@@ -233,12 +306,22 @@ own-selector override rule applies.
 `--bulma-carousel-indicator-line-height`, `--bulma-carousel-indicator-line-height-mobile`,
 `--bulma-carousel-indicator-line-radius`, `--bulma-carousel-indicator-line-width`,
 `--bulma-carousel-indicator-line-width-mobile`, `--bulma-carousel-indicator-size`,
-`--bulma-carousel-indicator-size-mobile`, `--bulma-carousel-overlay-arrow-background`,
+`--bulma-carousel-indicator-size-mobile`, `--bulma-carousel-item-gap`,
+`--bulma-carousel-items-in-view`, `--bulma-carousel-items-to-show`,
+`--bulma-carousel-items-to-show-desktop`, `--bulma-carousel-items-to-show-fullhd`,
+`--bulma-carousel-items-to-show-mobile`, `--bulma-carousel-items-to-show-tablet`,
+`--bulma-carousel-items-to-show-widescreen`, `--bulma-carousel-overlay-arrow-background`,
 `--bulma-carousel-overlay-arrow-background-hover`, `--bulma-carousel-overlay-arrow-color`,
 `--bulma-carousel-overlay-indicator-background`,
 `--bulma-carousel-overlay-indicator-background-active`,
 `--bulma-carousel-overlay-indicator-background-hover`, `--bulma-carousel-transition-duration`
 
+`--bulma-carousel-item-gap` (a length, default `0px`) is the space between items in view; set it
+on the carousel's own element through a class. The `--bulma-carousel-items-to-show*` variables
+come from the `itemsToShow*` props, and `--bulma-carousel-items-in-view` is the one of them the
+viewport picks. The props also decide how far a step moves, so set the count with the props
+rather than with these variables.
+
 ### Checkbox
 
 `--bulma-checkbox-active-color`, `--bulma-checkbox-background`, `--bulma-checkbox-border-color`,
@@ -247,6 +330,17 @@ own-selector override rule applies.
 `--bulma-checkbox-label-gap`, `--bulma-checkbox-radius`, `--bulma-checkbox-size`,
 `--bulma-checkbox-transition-duration`
 
+The check mark and the mixed dash are both `--bulma-checkbox-check-color`, on the
+`--bulma-checkbox-active-color` (checked) or `--bulma-checkbox-indeterminate-color` (mixed) fill,
+so a dark fill needs a light check color. Set these on a class you pass through `className`, not
+with `style`: Checkbox puts `style` and its other attributes on the hidden `<input>`, not on the
+`.styled-checkbox` label that declares them. Name both classes in the selector
+(`.styled-checkbox.my-box`, mind the class prefix) so it wins whatever order the stylesheets load
+in. A `color` prop declares both fills again on `.styled-checkbox.is-<color>`, which ties with
+that selector, so leave `color` unset when a class sets the fill. The unchecked border, `--bulma-checkbox-border-color`, defaults to `text-weak` so
+the box holds the 3:1 WCAG asks of a control's boundary; keep a replacement at 3:1 against what
+the form sits on.
+
 ### Collapse
 
 `--bulma-collapse-border-color`, `--bulma-collapse-group-gap`, `--bulma-collapse-header-weight`,
@@ -258,6 +352,30 @@ items of a `Collapses` group, which reads it with a 0.5rem fallback and declares
 so set it on the group or on any ancestor, `:root` included. (`Theme`'s `bulmaVars` does not
 list it, so set it in your CSS or through a `style` prop.)
 
+### Combobox
+
+Declared on the root, `.combobox`, and again on a menu rendered with `appendToBody`,
+`.combobox-menu.is-portal`, outside the root. A menu in place inherits the root's, so a value set on
+`.combobox` reaches it; for a portaled one, set it on `.combobox-menu.is-portal` as well, where
+they're declared. A lone `.combobox-menu` loses to that on specificity, and
+`.combobox-menu.is-portal` ties, so your rule wins only when it loads after the library styles. Each
+size class (`.is-small`, `.is-medium`, `.is-large`, on the root and on the menu) sets the item size
+and padding, so retune a size on that class. The highlight is the link color and its invert, the
+pair Bulma gives an active dropdown item, and the colors come from Bulma's tokens, so the list
+follows dark mode with no override. The menu reads these rather than Bulma's `--bulma-dropdown-*`,
+which Bulma declares on `.dropdown` alone.
+
+`--bulma-combobox-check-color`, `--bulma-combobox-check-gap`, `--bulma-combobox-check-size`,
+`--bulma-combobox-disabled-color`, `--bulma-combobox-divider-color`, `--bulma-combobox-empty-color`,
+`--bulma-combobox-group-label-color`, `--bulma-combobox-group-label-size`,
+`--bulma-combobox-group-label-weight`, `--bulma-combobox-highlight-background`,
+`--bulma-combobox-highlight-color`, `--bulma-combobox-item-color`,
+`--bulma-combobox-item-hover-background`, `--bulma-combobox-item-padding-x`,
+`--bulma-combobox-item-padding-y`, `--bulma-combobox-item-size`, `--bulma-combobox-list-max-height`,
+`--bulma-combobox-menu-background`, `--bulma-combobox-menu-border-color`,
+`--bulma-combobox-menu-offset`, `--bulma-combobox-menu-padding-y`, `--bulma-combobox-menu-radius`,
+`--bulma-combobox-menu-shadow`, `--bulma-combobox-menu-z-index`, `--bulma-combobox-portal-z-index`
+
 ### ContextMenu
 
 Both are declared on the box the menu hangs from, `.context-menu-content`, which is portaled away
@@ -368,6 +486,17 @@ Declared on the compound `.button.link-button` — see the compound-selector exc
 `--bulma-loading-overlay-opacity-opaque`, `--bulma-loading-text-color`,
 `--bulma-loading-text-size`
 
+### Menu
+
+`Menu.Section`'s, declared on the root, `.menu`, where Bulma declares its own `--bulma-menu-*`:
+the room between a section heading's words and its chevron, and the chevron's box, color and
+turn. The heading itself reads Bulma's label variables (`--bulma-menu-label-color`,
+`--bulma-menu-label-font-size`, `--bulma-menu-label-letter-spacing`,
+`--bulma-menu-label-spacing`), so retheming the menu's labels restyles section headings too.
+
+`--bulma-menu-section-chevron-color`, `--bulma-menu-section-chevron-duration`,
+`--bulma-menu-section-chevron-size`, `--bulma-menu-section-gap`
+
 ### Notification
 
 `--bulma-notification-delete-padding-inline-end` is the end padding of a notification with a close
@@ -383,6 +512,16 @@ sizes. Bulma's own `--bulma-notification-*` variables set the rest.
 `--bulma-numberinput-stepper-button-hover-bg`, `--bulma-numberinput-stepper-button-hover-color`,
 `--bulma-numberinput-stepper-width`
 
+### PinInput
+
+Declared on the row, `.pin-input`. Each box is a Bulma `.input`, so Bulma's `--bulma-input-*`
+variables color it, and a box's size comes from its size class. The gap and the caret's size are
+in `em`, so they follow the size of the boxes, and the caret is `currentColor`, the box's text.
+
+`--bulma-pin-input-box-width`, `--bulma-pin-input-caret-blink-duration`,
+`--bulma-pin-input-caret-color`, `--bulma-pin-input-caret-height`, `--bulma-pin-input-caret-width`,
+`--bulma-pin-input-gap`
+
 ### Picker popover (DateInput / TimeInput / DateTimeInput / DateRangeInput)
 
 `--bulma-picker-popover-animation-duration`, `--bulma-picker-popover-background`,
@@ -410,6 +549,12 @@ them. See the constituent-element exception above.
 `--bulma-radio-border-width`, `--bulma-radio-dot-color`, `--bulma-radio-focus-shadow-size`,
 `--bulma-radio-label-gap`, `--bulma-radio-size`, `--bulma-radio-transition-duration`
 
+As with Checkbox, set these on a class you pass through `className`, with both classes in the
+selector (`.styled-radio.my-radio`): `style` goes to the hidden `<input>`. A `color` prop
+declares `--bulma-radio-active-color` again on `.styled-radio.is-<color>`, which ties that
+selector, so leave `color` unset when a class sets it. The unchecked ring, `--bulma-radio-border-color`, defaults to `text-weak` for the same 3:1 boundary
+contrast.
+
 ### Rate
 
 `--bulma-rate-color-active`, `--bulma-rate-color-hover`, `--bulma-rate-color-inactive`,
@@ -597,22 +742,47 @@ custom dark-mode CSS keyed off `[data-theme='dark']` still matches, because `col
 Under dark mode Bulma flips the scheme/text/border/background lightness variables (e.g.
 `--bulma-scheme-main-l` 100% → 9%, `--bulma-text-l` 29% → 71%). Your brand color overrides from
 `Theme isRoot` or `:root` still apply on top, because they set the hue/saturation/lightness
-channels directly.
+channels directly. Each color's on-scheme lightness is the exception: Bulma gives dark mode its
+own, so a new color sets one per scheme (see "The lightnesses Bulma's build picks for contrast").
+
+### The scheme of the first paint
+
+`Theme` writes the attribute from an effect, and a client-rendered app (the create-bestax
+scaffold, for one) paints before its effects run. That first frame takes whatever `<html>`
+already carries: with nothing there, the visitor's OS scheme, which then flips. So the scheme
+for that frame comes from `index.html`:
+
+- **A scheme that never changes** goes on the `<html>` itself,
+  `<html lang="en" data-theme="light">`, and needs no `colorMode`.
+- **A scheme the visitor picks** is written by an inline script in `<head>`, from the saved
+  choice or else the OS preference, before anything renders. `examples/dark-mode.tsx` has the
+  script and the app's side: the app starts from the attribute the script wrote, passes its
+  state to `Theme colorMode` for the toggle, and saves each choice in `localStorage` under the
+  key the script reads. Keep it a plain inline script: one with `type="module"`, like the app's
+  own, waits until the whole page is parsed, which can be after the first paint.
+
+A prefixed flavor reads `data-bestax-theme`, so with one, `index.html` and the script write that
+attribute as well.
+
+Because the script always writes an attribute, custom dark-mode CSS keyed on `[data-theme='dark']`
+reaches every visitor. To offer the OS preference as a third choice, both sides change. The script
+writes no attribute for a saved `'system'`. The app adds `'system'` to its `ColorMode` and to what
+it reads back from storage, so it passes `colorMode="system"`, which keeps the attribute off, and
+its toggle becomes a choice of three, such as a `SegmentedControl`. With no attribute, Bulma's
+`prefers-color-scheme` rules apply from the first frame and follow the OS when it changes, and
+custom tokens then need both dark-mode paths (below).
 
 ### The single-mode contrast trap
 
-Because the OS preference applies whenever no `data-theme` attribute is set — the default state
-of every app that never configured `colorMode` — a light-only design silently breaks for any
-dark-mode visitor: Bulma's text goes near-white while author-defined fixed tokens stay light —
+Because the OS preference applies whenever no `data-theme` attribute is set, which is the
+default state of every app that never sets one, a light-only design silently breaks for any
+dark-mode visitor: Bulma's text goes near-white while author-defined fixed tokens stay light,
 white text on cream. The failure is invisible unless the author's own OS is in dark mode.
 
-**If the design is single-mode, pin the scheme** so text can't flip out from under the palette:
-
-```tsx
-<Theme isRoot colorMode="light">
-  <App />
-</Theme>
-```
+**If the design is single-mode, pin the scheme** on the `<html>` in `index.html`
+(`<html lang="en" data-theme="light">`, as above), so text can't flip out from under the palette.
+`<Theme isRoot colorMode="light">` pins it too, but only from its effect on, after the first
+paint.
 
 **If both modes are supported, never expose a fixed custom token to the flip** — derive it from
 scheme variables, or flip it yourself:

package/templates/skills/bestax-theming/references/themeable-components.md

@@ -60,6 +60,7 @@ Shades (`colorShade` / `backgroundColorShade`): `00, 05, 10, … 95, invert, lig
 | `SubTitle`         | — (no `color`; use `textColor`)                                                                                                                                           | `1`–`6` (string or number)                                                | `size` also sets the heading level unless `as="p"` (an `<h1>` with neither): pair `as` with `textSize` instead                                      |
 | `Autocomplete`     | `primary \| link \| info \| success \| warning \| danger`                                                                                                                 | `small \| medium \| large`                                                | the 6 only                                                                                                                                          |
 | `Checkbox`         | `primary \| link \| info \| success \| warning \| danger`                                                                                                                 | `small \| normal \| medium \| large`                                      | the 6 only                                                                                                                                          |
+| `Combobox`         | none on the root (`Combobox.Input` takes `Input`'s `color`)                                                                                                               | `small \| medium \| large`                                                | sizes the field and the items together; the highlight is `--bulma-combobox-highlight-*`; `--bulma-combobox-*`                                       |
 | `DateInput`        | `primary \| link \| info \| success \| warning \| danger`                                                                                                                 | `small \| medium \| large`                                                | also `isRounded`                                                                                                                                    |
 | `DateRangeInput`   | `primary \| link \| info \| success \| warning \| danger`                                                                                                                 | `small \| medium \| large`                                                | also `isRounded`; `color` also fills the calendar range                                                                                             |
 | `DateTimeInput`    | `primary \| link \| info \| success \| warning \| danger`                                                                                                                 | `small \| medium \| large`                                                | also `isRounded`                                                                                                                                    |
@@ -72,6 +73,7 @@ Shades (`colorShade` / `backgroundColorShade`): `00, 05, 10, … 95, invert, lig
 | `Loading`          | `primary \| link \| info \| success \| warning \| danger`                                                                                                                 | `small \| medium \| large`                                                | spinner color; default light grey                                                                                                                   |
 | `Navbar`           | `primary \| link \| info \| success \| warning \| danger \| black \| dark \| light \| white`                                                                              | —                                                                         | —                                                                                                                                                   |
 | `Numberinput`      | `primary \| link \| info \| success \| warning \| danger \| light \| dark`                                                                                                | `small \| medium \| large`                                                | also `inputColor` (the 6) for the inner input                                                                                                       |
+| `PinInput`         | `primary \| link \| info \| success \| warning \| danger \| black \| dark \| light \| white`                                                                              | `small \| medium \| large`                                                | each box is a Bulma `.input`, so `--bulma-input-*` theme it; also `isRounded`; `--bulma-pin-input-*`                                                |
 | `Pagination`       | `primary \| link \| info \| success \| warning \| danger \| black \| dark \| light \| white`                                                                              | `small \| medium \| large`                                                | **entire `color` prop deprecated** (no CSS ships; dev-warn; removal next major)                                                                     |
 | `Panel`            | `primary \| link \| info \| success \| warning \| danger \| black \| dark \| light \| white`                                                                              | —                                                                         | —                                                                                                                                                   |
 | `Progress`         | every `validColors` member (the `-bis`/`-ter` shades and the greys deprecated: no CSS, dev-warn, removed next major — see ⚠️)                                             | `small \| medium \| large`                                                | —                                                                                                                                                   |

package/templates/vite/package.json

@@ -10,7 +10,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@allxsmith/bestax-bulma": "^5.0.0",
+    "@allxsmith/bestax-bulma": "workspace:^",
     "react": "^19.2.3",
     "react-dom": "^19.2.3"
   },

package/templates/vite/src/main.jsx

@@ -2,7 +2,7 @@ import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 
 // Bestax's stylesheet loads before the app's own CSS, so a named class in
-// src/App.css wins over a Bulma rule of the same weight.
+// src/index.css wins over a Bulma rule of the same weight.
 import '@allxsmith/bestax-bulma/bestax.css';
 import './index.css';
 import App from './App.jsx';

package/templates/vite-ts/package.json

@@ -10,7 +10,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@allxsmith/bestax-bulma": "^5.0.0",
+    "@allxsmith/bestax-bulma": "workspace:^",
     "react": "^19.2.3",
     "react-dom": "^19.2.3"
   },

package/templates/vite-ts/src/main.tsx

@@ -2,7 +2,7 @@ import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 
 // Bestax's stylesheet loads before the app's own CSS, so a named class in
-// src/App.css wins over a Bulma rule of the same weight.
+// src/index.css wins over a Bulma rule of the same weight.
 import '@allxsmith/bestax-bulma/bestax.css';
 import './index.css';
 import App from './App.tsx';