create-bestax 4.2.15 → 4.2.17

package/templates/skills/bestax-layout-scaffold/references/archetypes.md

@@ -239,6 +239,63 @@ build the whole grid with `Grid`/`Cell` (`<Grid isFixed fixedColsMobile={1} fixe
 fixedColsDesktop={3} gap={4}>`) — CSS Grid keeps cells equal-height for free; see the
 `Grid / Cell` section in `layout-components.md`.
 
+**Nothing to show:** when the collection is empty, or a search or a filter matches nothing,
+render an `EmptyState` in the grid's place rather than composing one from `Box`, `Icon` and
+`Title`. Its `title` is always a heading: set `titleAs` to the level under the section's own
+heading. It doesn't announce itself, so a search keeps a status region beside its field the
+whole time, saying the count, and "Clear search" puts focus back in the field, since the button
+goes away with the empty state:
+
+```tsx
+const searchRef = useRef<HTMLInputElement>(null);
+const shown = items.filter(item =>
+  item.name.toLowerCase().includes(query.trim().toLowerCase())
+);
+
+<>
+  <Field label="Search products">
+    <Control>
+      <Input
+        ref={searchRef}
+        type="search"
+        value={query}
+        onChange={e => setQuery(e.target.value)}
+      />
+    </Control>
+  </Field>
+  {/* Always in the page, so a change to its text is announced. */}
+  <Paragraph role="status" aria-atomic="true" visibility="sr-only">
+    {shown.length === 0
+      ? 'No products match the search'
+      : `${shown.length} products`}
+  </Paragraph>
+  {shown.length === 0 ? (
+    <EmptyState
+      icon="magnifying-glass"
+      title={`No products match “${query}”`}
+      titleAs="h2"
+      description="Check the spelling, or clear the search."
+    >
+      <Button
+        onClick={() => {
+          setQuery('');
+          searchRef.current?.focus();
+        }}
+      >
+        Clear search
+      </Button>
+    </EmptyState>
+  ) : (
+    <Columns isMultiline>{/* the cards, as above */}</Columns>
+  )}
+</>;
+```
+
+With nothing in the collection at all, the same component says so and offers the first step:
+`<EmptyState icon="box-open" title="No products yet" titleAs="h2" description="…">` with one
+`<Button color="primary">` as its child, or two or more in `EmptyState.Actions`. While the items
+load, show a `Skeleton` or a `Loader` instead, so the empty state doesn't flash first.
+
 ---
 
 ## Combining archetypes

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

@@ -54,8 +54,8 @@ leftover would be a type error rather than a no-op.
 | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `isColor="primary"`                                                                                          | `color="primary"` (every component that had it)                                                                                                                                                                                                                           |
 | `isSize="large"`                                                                                             | `size="large"` — Button, Content, Delete, Icon, Input, Progress, Section, Select, Tag, TextArea, Breadcrumb, Pagination, Tabs, Field.Label, Modal.Close                                                                                                                   |
-| `Title isSize={3}`                                                                                           | `size={3}` — bestax accepts the numbers 1–6                                                                                                                                                                                                                               |
-| `Subtitle isSize={4}`                                                                                        | `SubTitle size={4} as="h2"` — bloomer's default was an `<h2>`, bestax's is an `<h1>`, so the level is kept                                                                                                                                                                |
+| `Title isSize={3}`                                                                                           | `textSize="3"`, so the `<h1>` stays an `<h1>` (see [Title and Subtitle sizes](#title-and-subtitle-sizes))                                                                                                                                                                 |
+| `Subtitle isSize={4}`                                                                                        | `SubTitle textSize="4" as="h2"`: bloomer's default was an `<h2>`, bestax's is an `<h1>`, so the level is written out                                                                                                                                                      |
 | `Image isSize="128x128"`                                                                                     | `size="128x128"`                                                                                                                                                                                                                                                          |
 | `Image isRatio="16:9"`                                                                                       | `size="16by9"` (`square`→`square`, `1:1`→`1by1`, `4:3`→`4by3`, `3:2`→`3by2`, `2:1`→`2by1`)                                                                                                                                                                                |
 | `Breadcrumb isAlign`                                                                                         | `alignment`                                                                                                                                                                                                                                                               |
@@ -77,6 +77,31 @@ leftover would be a type error rather than a no-op.
 | `isActive` on Dropdown, DropdownItem, MenuLink, Modal, NavbarBurger, NavbarMenu, NavbarItem, PanelBlock, Tab | `active`                                                                                                                                                                                                                                                                  |
 | `Input`, `Select`, `TextArea`                                                                                | `InputBase`, `SelectBase`, `TextAreaBase` — bloomer's were bare elements; bestax's `Input`/`Select`/`TextArea` wrap themselves in `Field` and `Control`, so the bare `*Base` exports are the faithful targets and your existing `Field`/`Control` markup stays as written |
 
+## Title and Subtitle sizes
+
+bloomer's `Title` rendered an `<h1>` and its `Subtitle` an `<h2>` whatever `isSize` said, or
+the element `tag` named. bestax's `Title` and `SubTitle` render the heading their `size` names
+unless `as="p"`, so `<SubTitle size={4} as="h2">` is an `<h4>`. The codemod keeps the element
+bloomer rendered:
+
+| bloomer                       | bestax-bulma                      | renders |
+| ----------------------------- | --------------------------------- | ------- |
+| `<Title isSize={4}>`          | `<Title textSize="4">`            | `<h1>`  |
+| `<Title isSize={1}>`          | `<Title size={1}>`                | `<h1>`  |
+| `<Title isSize={4} tag="h2">` | `<Title textSize="4" as="h2">`    | `<h2>`  |
+| `<Title isSize={6} tag="p">`  | `<Title size={6} as="p">`         | `<p>`   |
+| `<Subtitle>`                  | `<SubTitle as="h2">`              | `<h2>`  |
+| `<Subtitle isSize={2}>`       | `<SubTitle size={2}>`             | `<h2>`  |
+| `<Subtitle isSize={4}>`       | `<SubTitle textSize="4" as="h2">` | `<h2>`  |
+
+`size` stays only where it renders the same element: a `<p>`, or the heading the size names.
+Everywhere else the size moves to the `textSize` helper, and so does a 7, which bestax's `size`
+does not take. The helper sets the same font size through Bulma's `is-size-4` class rather than the
+title's own `is-4`, so a rule of your own that targets `.title.is-4` needs the new class too.
+`is-size-4` is also `!important`, so a font size your own CSS gives the title, such as
+`.hero .title`, now loses to it where it used to beat `is-4`. A literal outside 1 to 7 keeps `size`
+and gets a `prop:isSize` TODO.
+
 ## Column sizes
 
 | bloomer                                                  | bestax-bulma                                                                                                      |
@@ -161,12 +186,13 @@ value is flagged. The same conversion covers the modifiers bestax has no prop fo
 
 ## Refs
 
-bloomer forwarded no refs. bestax forwards a ref from the form controls, plus `Avatar`,
-`Button`, `Carousel`, `CarouselItem`, `Dialog`, `Dropdown`, `Link`, `LinkButton`, `Loader`,
-`Menu.Item`, `Modal`, `Navbar`, `Navbar.Burger`, `Navbar.Dropdown`, `Navbar.Item`,
-`Navbar.Link`, `Sidebar` and `Toast` — pass `ref` directly on those. "The form controls" means
-the inputs themselves: the `Field`, `Field.Label`, `Field.Body`, `Checkboxes` and `Radios`
-wrappers around them forward nothing.
+bloomer forwarded no refs. bestax forwards a ref from 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`, `Toast` and
+`ToggleButton` — pass `ref` directly on those. "The form controls" means the inputs themselves: the
+`Field`, `Field.Label`, `Field.Body`, `Checkboxes` and `Radios` wrappers around them forward
+nothing.
 
 A `ref` on anything else is unsupported, and the two React majors fail differently: React 18
 drops it and logs "Function components cannot be given refs", while React 19 hands it to the

package/templates/skills/bestax-migrate/references/bloomer/unmappables.md

@@ -274,6 +274,24 @@ prop conditionally:
 counterpart in bestax (only `isNarrowTouch`) — Bulma keeps the `is-*-touch` classes, so use
 `className`.
 
+## `prop:isSize` on `Title` and `Subtitle`: a size the codemod cannot carry
+
+bloomer's `Title` and `Subtitle` kept their element at every size. bestax's render the heading
+their `size` names, so a literal `isSize` moves to `textSize` to keep the level (see "Title and
+Subtitle sizes" in the prop map). A dynamic one cannot move, because `textSize` takes a string,
+so it becomes `size`. Pass it to `textSize` yourself:
+
+```jsx
+<Subtitle isSize={compact ? 5 : 4}>Report</Subtitle>
+<SubTitle textSize={compact ? '5' : '4'} as="h2">Report</SubTitle>
+```
+
+A literal outside 1 to 7 has no Bulma class, and bestax renders none for it either: drop it, or set
+a `textSize` from `'1'` to `'7'`.
+
+A dynamic size beside `tag="p"` is not flagged, since bestax never turns a `<p>` into a
+heading.
+
 ## `value-reference` — a component used as a value
 
 `const Wrapped = Box` and `{ Subtitle }` are rewritten to the bestax binding (`Hero.Foot`,

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

@@ -118,6 +118,29 @@ wrong:
   Note that this one does change the rendered element: rbx's `forwardRefAs` rendered the tag you
   gave it, so that really was a `<span>`, and the TODO exists to tell you the element moved.
 
+## Title sizes
+
+rbx's `Title` rendered an `<h1>` at every size, subtitle or not, or the element `as` named.
+bestax's `Title` and `SubTitle` render the heading their `size` names unless `as="p"`, so the
+codemod keeps the element rbx rendered:
+
+| rbx                                | bestax-bulma                   | renders |
+| ---------------------------------- | ------------------------------ | ------- |
+| `<Title size={4}>`                 | `<Title textSize="4">`         | `<h1>`  |
+| `<Title size={1}>`                 | `<Title size={1}>`             | `<h1>`  |
+| `<Title subtitle size={6}>`        | `<SubTitle textSize="6">`      | `<h1>`  |
+| `<Title as="h2" size={5}>`         | `<Title as="h2" textSize="5">` | `<h2>`  |
+| `<Title as="p" subtitle size={5}>` | `<SubTitle as="p" size={5}>`   | `<p>`   |
+
+`size` stays only where it renders the same element: a `<p>`, or the heading the size names.
+Everywhere else the size moves to the `textSize` helper, and so does a 7, which bestax's `size`
+does not take. The helper sets the same font size through Bulma's `is-size-4` class rather than the
+title's own `is-4`, so a rule of your own that targets `.title.is-4` needs the new class too.
+`is-size-4` is also `!important`, so a font size your own CSS gives the title, such as
+`.hero .title`, now loses to it where it used to beat `is-4`. Beside a spread, which may carry
+`as`, a size moves even where it names the default `<h1>`. A literal outside 1 to 7 keeps `size`
+and gets a `prop:size` TODO.
+
 ## `href` follows `as`
 
 bestax gives an element the attributes of the tag `as` names, so `href` exists only where that
@@ -156,13 +179,14 @@ becomes.
 Beside a `ref` the element already has, a rename leaves `innerRef` in place with a `prop:innerRef`
 TODO rather than write a second `ref`; keep whichever one you meant.
 
-An existing `ref` is passed through untouched — which is safe only where the bestax target
-forwards one. rbx forwards a ref on every component; bestax does so on the form controls, plus
-`Avatar`, `Button`, `Carousel`, `CarouselItem`, `Dialog`, `Dropdown`, `Link`, `LinkButton`,
-`Loader`, `Menu.Item`, `Modal`, `Navbar`, `Navbar.Burger`, `Navbar.Dropdown`, `Navbar.Item`,
-`Navbar.Link`, `Sidebar` and `Toast`. "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.
+An existing `ref` is passed through untouched — which is safe only where the bestax target forwards
+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`, `Toast` and
+`ToggleButton`. "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.
 
 Carry a `ref` onto anything else — `Card`, `Box`, `Section`, `Message`, `Tabs` and most of the
 catalogue — and it is unsupported, but the two React majors fail differently. React 18 drops

package/templates/skills/bestax-migrate/references/rbx/unmappables.md

@@ -171,22 +171,49 @@ converted — bestax has its own unrelated `responsive` prop (`'mobile' | 'narro
 half-emptied rbx object behind would be a type error rather than a leftover. The TODO names
 which breakpoints did not carry.
 
+## A size bestax doesn't take (`prop:size`)
+
+`Button.Group`, `Tag.Group` and `Message` sizes carry over as written when bestax's `Buttons`,
+`Tags` or `Message` takes the value. Any other value, or one the codemod can't read, stays as
+written with a TODO that lists the sizes that component takes: use one of them, or drop the
+prop.
+
+A dynamic `Image.Container` size gets the same rule, since the codemod can't turn it into
+bestax's `NxN` form. Set `size` on the migrated `<Image>` by hand.
+
+## `prop:size` on `Title`: a size the codemod cannot carry
+
+rbx's `Title` rendered an `<h1>` at every size, subtitle or not. bestax's `Title` and `SubTitle`
+render the heading their `size` names unless `as="p"`, so a literal size moves to `textSize` to
+keep the level (see "Title sizes" in the prop map). A dynamic one cannot move, because
+`textSize` takes a string, so it stays `size`. Pass it to `textSize` yourself:
+
+```jsx
+<Title size={compact ? 5 : 4}>Report</Title>
+<Title textSize={compact ? '5' : '4'}>Report</Title>
+```
+
+A literal outside 1 to 7 has no Bulma class, and bestax renders none for it either: drop it, or set
+a `textSize` from `'1'` to `'7'`.
+
+The same TODO marks a `Title` that sets `size` and `textSize` both: drop `size` and let
+`textSize` set the font size.
+
 ## Props with no counterpart
 
-| TODO                                               | What to do                                                                                                                                                                                                                                               |
-| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `prop:closeOnBlur` on `Modal`                      | the migrated compound form renders `Modal.Background` as you wrote it; wire its `onClick` to your `onClose`                                                                                                                                              |
-| `prop:selected`, `prop:text` on `Button`           | `className="is-selected"`; for `is-text` use `color="ghost"` or a link                                                                                                                                                                                   |
-| `prop:size` on `Button.Group` / `Tags` / `Message` | set `size` on each child instead                                                                                                                                                                                                                         |
-| `prop:gradient` on `Hero`                          | Bulma v1 removed `is-bold` gradients; use `bgColor` or a custom class                                                                                                                                                                                    |
-| `prop:color`, `prop:vertical` on `Divider`         | bestax's `Divider` takes only `bgColor` and renders an `<hr>`                                                                                                                                                                                            |
-| `component:Divider` (a labelled divider)           | rbx rendered `<Divider>OR</Divider>`'s children as a centred label via `data-content`; bestax's `Divider` is a bare `<hr>` and takes no children -- React rejects children on a void element at runtime. Put the label in surrounding markup, or drop it |
-| `prop:direction` on `PageLoader`                   | no directional variant; drop it or add a class                                                                                                                                                                                                           |
-| `prop:managed`                                     | bestax components are uncontrolled; drive the `Modal` with `active` and `onClose`                                                                                                                                                                        |
-| `prop:document` on `Modal`                         | bestax portals via `portal`, but it takes `true`, a selector or an element rather than a `Document` — see [Modal: what carries over](#modal-what-carries-over)                                                                                           |
-| `prop:document` on `Navbar`                        | bestax's `Navbar` has no `document` prop; drop it                                                                                                                                                                                                        |
-| `badgeOutlined`, `badgeRounded`, `badgeSize`       | bestax's `Badge` has no outline, pill or size variant                                                                                                                                                                                                    |
-| `tooltipResponsive`                                | bestax's `Tooltip` has one `position` for all viewports                                                                                                                                                                                                  |
+| TODO                                         | What to do                                                                                                                                                                                                                                               |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prop:closeOnBlur` on `Modal`                | the migrated compound form renders `Modal.Background` as you wrote it; wire its `onClick` to your `onClose`                                                                                                                                              |
+| `prop:selected`, `prop:text` on `Button`     | `className="is-selected"`; for `is-text` use `color="ghost"` or a link                                                                                                                                                                                   |
+| `prop:gradient` on `Hero`                    | Bulma v1 removed `is-bold` gradients; use `bgColor` or a custom class                                                                                                                                                                                    |
+| `prop:color`, `prop:vertical` on `Divider`   | bestax's `Divider` takes only `bgColor` and renders an `<hr>`                                                                                                                                                                                            |
+| `component:Divider` (a labelled divider)     | rbx rendered `<Divider>OR</Divider>`'s children as a centred label via `data-content`; bestax's `Divider` is a bare `<hr>` and takes no children -- React rejects children on a void element at runtime. Put the label in surrounding markup, or drop it |
+| `prop:direction` on `PageLoader`             | no directional variant; drop it or add a class                                                                                                                                                                                                           |
+| `prop:managed`                               | bestax components are uncontrolled; drive the `Modal` with `active` and `onClose`                                                                                                                                                                        |
+| `prop:document` on `Modal`                   | bestax portals via `portal`, but it takes `true`, a selector or an element rather than a `Document` — see [Modal: what carries over](#modal-what-carries-over)                                                                                           |
+| `prop:document` on `Navbar`                  | bestax's `Navbar` has no `document` prop; drop it                                                                                                                                                                                                        |
+| `badgeOutlined`, `badgeRounded`, `badgeSize` | bestax's `Badge` has no outline, pill or size variant                                                                                                                                                                                                    |
+| `tooltipResponsive`                          | bestax's `Tooltip` has one `position` for all viewports                                                                                                                                                                                                  |
 
 ## Modal: what carries over
 

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

@@ -20,7 +20,7 @@ codemod converts it; **Flagged** = it leaves a `TODO(bestax-migrate)` comment (s
 | `Element`      | —                                            | Flagged: no generic element; use a semantic component + helper props                                                                                |
 | `Footer`       | `Footer`                                     | Auto                                                                                                                                                |
 | `Form.*`       | flat imports                                 | See Form table below                                                                                                                                |
-| `Heading`      | `Title` / `SubTitle` / `<p class="heading">` | Auto for literal `subtitle`/`heading` (by value, not presence — `subtitle={false}` is `Title`); dynamic value flagged                               |
+| `Heading`      | `Title` / `SubTitle` / `<p class="heading">` | Auto for literal `subtitle`/`heading` (by value, not presence — `subtitle={false}` is `Title`); dynamic value flagged; `size` may become `textSize` |
 | `Hero`         | `Hero`                                       | Auto; `hasNavbar`→`fullheightWithNavbar`; `halfheight`/`gradient` flagged                                                                           |
 | `Icon`         | `Icon`                                       | `<i class="fas fa-x">` children → `name`/`library`/`variant` props; else flagged                                                                    |
 | `Image`        | `Image`                                      | Auto; numeric `size={128}` → `size="128x128"`, `rounded`→`isRounded`                                                                                |
@@ -28,7 +28,7 @@ codemod converts it; **Flagged** = it leaves a `TODO(bestax-migrate)` comment (s
 | `Loader`       | plain `<div className="loader">`             | Auto (Bulma v1 still ships the class); swap in bestax's `Loader` by hand for its progressbar role and accessible name                               |
 | `Media`        | `Media`                                      | Auto                                                                                                                                                |
 | `Menu`         | `Menu`                                       | Auto                                                                                                                                                |
-| `Message`      | `Message`                                    | Auto; `size` flagged                                                                                                                                |
+| `Message`      | `Message`                                    | Auto; unknown or dynamic `size` flagged                                                                                                             |
 | `Modal`        | `Modal`                                      | `show`→`active`, `closeOnEsc`→`closeOnEscape`; `closeOnBlur`/`showClose` flagged (compound form renders neither)                                    |
 | `Navbar`       | `Navbar`                                     | Auto; see dropdown note below                                                                                                                       |
 | `Notification` | `Notification`                               | Auto; `light`→`isLight`                                                                                                                             |
@@ -46,7 +46,7 @@ codemod converts it; **Flagged** = it leaves a `TODO(bestax-migrate)` comment (s
 | RBC                                                         | bestax                                                                   |
 | ----------------------------------------------------------- | ------------------------------------------------------------------------ |
 | `Breadcrumb.Item`                                           | plain `<li><a href=…>` (`active` → `is-active`)                          |
-| `Button.Group`                                              | `Buttons` (`align="right"`→`isRight`)                                    |
+| `Button.Group`                                              | `Buttons` (`align="right"`→`isRight`); unknown or dynamic `size` flagged |
 | `Card.Header` / `.Title` / `.Icon`                          | `Card.Header` / `.Header.Title` / `.Header.Icon`                         |
 | `Card.Image`                                                | `Card.Image` wrapping an inner `<Image>`                                 |
 | `Card.Content`                                              | `Card.Content`                                                           |

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

@@ -46,6 +46,28 @@ href="/x">`) keeps the element and drops the `href`, with a `prop:href` TODO. RB
 `<Button href="/x">` with no `renderAs` goes the same way: bestax's `Button` renders a
 `<button>`. Set `as="a"` to make it a link.
 
+## `Heading` sizes
+
+RBC's `Heading` rendered an `<h1>` at every size, subtitle or not, or the element `renderAs`
+named. bestax's `Title` and `SubTitle` render the heading their `size` names unless `as="p"`, so
+the codemod keeps the element RBC rendered:
+
+| RBC                                        | bestax-bulma                   | renders |
+| ------------------------------------------ | ------------------------------ | ------- |
+| `<Heading size={4}>`                       | `<Title textSize="4">`         | `<h1>`  |
+| `<Heading size={1}>`                       | `<Title size="1">`             | `<h1>`  |
+| `<Heading subtitle size={6}>`              | `<SubTitle textSize="6">`      | `<h1>`  |
+| `<Heading renderAs="h2" size={5}>`         | `<Title as="h2" textSize="5">` | `<h2>`  |
+| `<Heading renderAs="p" subtitle size={5}>` | `<SubTitle as="p" size="5">`   | `<p>`   |
+
+`size` stays only where it renders the same element: a `<p>`, or the heading the size names.
+Everywhere else the size moves to the `textSize` helper, and so does a 7, which bestax's `size`
+does not take. The helper sets the same font size through Bulma's `is-size-4` class rather than the
+title's own `is-4`, so a rule of your own that targets `.title.is-4` needs the new class too.
+`is-size-4` is also `!important`, so a font size your own CSS gives the title, such as
+`.hero .title`, now loses to it where it used to beat `is-4`. A literal outside 1 to 7 keeps `size`
+and gets a `prop:size` TODO.
+
 ## Boolean modifier convention
 
 RBC uses bare booleans (`loading`, `outlined`, `rounded`, `fullwidth`); bestax prefixes

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

@@ -129,22 +129,47 @@ 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` / Hero `gradient` / Hero `halfheight` (`prop:size`)
 
 - `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.
 
+## A size bestax doesn't take (`prop:size` on `Button.Group` and `Message`)
+
+`Button.Group` and `Message` sizes carry over as written when bestax's `Buttons` or `Message`
+takes the value. Any other value, or one the codemod can't read, stays as written with a TODO
+that lists the sizes that component takes: use one of them, or drop the prop.
+
+## `prop:size` on `Heading`: a size the codemod cannot carry
+
+RBC's `Heading` rendered an `<h1>` at every size, subtitle or not. bestax's `Title` and
+`SubTitle` render the heading their `size` names unless `as="p"`, so a literal size moves to
+`textSize` to keep the level (see "`Heading` sizes" in the prop map). A dynamic one cannot move,
+because `textSize` takes a string, so it stays `size`. Pass it to `textSize` yourself:
+
+```jsx
+<Heading size={compact ? 5 : 4}>Report</Heading>
+<Title textSize={compact ? '5' : '4'}>Report</Title>
+```
+
+A literal outside 1 to 7 has no Bulma class, and bestax renders none for it either: drop it, or set
+a `textSize` from `'1'` to `'7'`.
+
+The same TODO marks a `Heading` that sets `size` and `textSize` both: drop `size` and let
+`textSize` set the font size.
+
 ## `domRef`
 
-bestax components don't take `domRef`, but many forward a plain `ref` — the form controls,
-plus `Avatar`, `Button`, `Carousel`, `CarouselItem`, `Dialog`, `Dropdown`, `Link`,
-`LinkButton`, `Loader`, `Menu.Item`, `Modal`, `Navbar`, `Navbar.Burger`, `Navbar.Dropdown`,
-`Navbar.Item`, `Navbar.Link`, `Sidebar` and `Toast`. 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.
+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`, `Toast` and `ToggleButton`. 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.
 
 Everywhere else the rename is not enough, and the two React majors differ: React 18 drops the
 ref and logs "Function components cannot be given refs", while React 19 passes it through as

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

@@ -126,6 +126,8 @@ partial inventory, and a worked example are in `references/modular-build.md`.
   `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.
+  When the app does render Material Symbols, its font can be made smaller instead of
+  removed: see [Making the font smaller](https://bestax.io/docs/guides/getting-started/alternative-icons#making-the-font-smaller).
 
 ## References
 

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

@@ -73,15 +73,15 @@ Every extras partial that exists (from the library's `src/scss/**/_index.scss`
 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`, `steps`, `sidebar`, `toast`, `dialog`, `carousel`,
-`tabs`, `reveal`, `avatar`, `avatars`, `badge`
+`loading`, `collapse`, `tooltip`, `popover`, `hovercard`, `contextmenu`, `steps`, `sidebar`,
+`toast`, `dialog`, `carousel`, `tabs`, `reveal`, `avatar`, `avatars`, `badge`, `emptystate`
 
 **Form** (`@allxsmith/bestax-bulma/scss/form/<name>`):
 `checkbox`, `radio`, `switch`, `slider`, `numberinput`, `rate`, `autocomplete`, `taginput`,
 `picker-popover`, `dateinput`, `timeinput`, `datetimeinput`, `daterangeinput`
 
-**Elements** (`@allxsmith/bestax-bulma/scss/elements/<name>`): `linkbutton`, `loader`,
-`progress`, `skeleton`
+**Elements** (`@allxsmith/bestax-bulma/scss/elements/<name>`): `kbd`, `linkbutton`, `loader`,
+`notification`, `progress`, `skeleton`
 
 **Helpers** (`@allxsmith/bestax-bulma/scss/helpers/<name>`): `cursor`, `sizing`
 
@@ -96,6 +96,8 @@ Notes:
   `picker-popover` too.
 - `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`, so include it next to the Bulma
@@ -105,6 +107,10 @@ Notes:
   `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.
+- `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.
 - 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.
@@ -154,12 +160,13 @@ not `flexbox` — `flexbox` holds only the alignment props. Verified failure mod
 
 The `npm create bestax` starter renders `Container`, `Section`, `Columns`/`Column`, `Image`,
 `Title`/`SubTitle`, `Box`, `Card`, `Buttons`/`Button`, and `Notification` with its close
-button: all stock Bulma, no bestax extras. Its helper props are `display` (visibility),
-`flexGrow` (flexbox), and `textAlign` (typography); it uses no spacing or color props. That
-inventory compiles to the following, verified pixel-equivalent to the prebuilt `complete`
-flavor in headless Chromium (light and dark, phone and desktop width, notification open), at
-274 KB raw / 30 KB gzip vs 819 KB / 84 KB. Scaffolded with an icon library, the starter also
-needs `bulma/sass/elements/icon` for its `IconText` card titles:
+button: all stock Bulma, plus the `notification` extras partial for that close button. Its
+helper props are `display` (visibility), `flexGrow` (flexbox), and `textAlign` (typography);
+it uses no spacing or color props. That inventory compiles to the following, verified
+pixel-equivalent to the prebuilt `complete` flavor in headless Chromium (light and dark, phone
+and desktop width, notification open), at 274 KB raw / 30 KB gzip vs 819 KB / 84 KB.
+Scaffolded with an icon library, the starter also needs `bulma/sass/elements/icon` for its
+`IconText` card titles:
 
 ```scss
 // src/styles.scss
@@ -184,6 +191,8 @@ needs `bulma/sass/elements/icon` for its `IconText` card titles:
 @use 'bulma/sass/helpers/visibility'; // display="flex"
 @use 'bulma/sass/helpers/flexbox'; // flexGrow
 @use 'bulma/sass/helpers/typography'; // textAlign
+
+@use '@allxsmith/bestax-bulma/scss/elements/notification'; // text clears the close button
 ```
 
 ```tsx

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

@@ -20,7 +20,10 @@ 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.
+  scope the variables to the wrapped subtree. A `Theme` only reaches variables the component
+  inherits: Bulma declares component variables such as `--bulma-card-radius` on the component's
+  own element, so a `Theme` value for one never applies (it warns in development). Set those on
+  the component with `className` or `style` instead (see `references/css-variables.md`).
 - **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.