create-bestax 4.2.13 → 4.2.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bestax",
-  "version": "4.2.13",
+  "version": "4.2.15",
   "description": "Create a new bestax-bulma project",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
     "prompts": "^2.4.2",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@allxsmith/bestax-bulma": "^5.27.0"
+    "@allxsmith/bestax-bulma": "^5.27.4"
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",
@@ -78,5 +78,5 @@
     "clean": "rimraf dist",
     "release": "npx semantic-release"
   },
-  "readme": "# create-bestax\n\n[![npm version](https://img.shields.io/npm/v/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![npm downloads](https://img.shields.io/npm/dm/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://badge.socket.dev/npm/package/create-bestax/latest)](https://socket.dev/npm/package/create-bestax/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14361/badge)](https://www.bestpractices.dev/projects/14361)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/create-bestax#provenance)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nThe scaffolder for [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) — spin up a Vite app pre-wired for the **Bulma v1** React component library in one command. Picks your framework (JS or TypeScript), CSS flavor, and icon library, and can drop in the bestax **AI skills** so an agent like Claude Code knows the library from the first prompt.\n\nPart of the [bestax monorepo](https://github.com/allxsmith/bestax) — see also [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) for the components themselves.\n\n## Requirements\n\n- **Node.js 22 or newer.** Node 18 and 20 are both past end-of-life. On an older runtime the\n  CLI exits immediately with an explicit upgrade message.\n- npm 10 or newer (ships with Node 22), or yarn/pnpm.\n\n## Usage\n\n### Quick Start\n\n```bash\n# Using npm\nnpm create bestax@latest my-app\n\n# Using npx\nnpx create-bestax@latest my-app\n\n# Alternative naming\nnpm create bestax-bulma@latest my-app\n```\n\n### Interactive Mode\n\nRunning without arguments will prompt you for all options:\n\n```bash\nnpm create bestax@latest\n```\n\nYou'll be asked to:\n\n1. Enter a project name (and, if that directory already holds files, confirm removing them;\n   nothing is removed until you have answered the last question)\n2. Select a framework (Vite or Vite + TypeScript)\n3. Choose a Bulma CSS flavor (Complete or Minimal)\n4. Select an icon library (Font Awesome, Material Icons, etc.)\n5. Choose whether to install the bestax AI skills into `.claude/skills/`\n\nEvery prompt has a flag equivalent, so the whole flow is scriptable and CI-friendly — see the options below.\n\n### Command Line Options\n\n```bash\nnpm create bestax@latest [project-directory] [options]\n```\n\n**Arguments:**\n\n- `[project-directory]` - Optional project directory name. It also becomes the `package.json`\n  name, lower-cased the way `npm init` does and without a leading `_`, since npm rejects both.\n\n**Options:**\n\n- `-t, --template <template>` - Template to use: `vite` or `vite-ts`  \n  **Default:** `vite`\n- `-b, --bulma <flavor>` - Bulma CSS flavor:\n  - `complete` - Full Bulma CSS with all components and helpers\n  - `prefixed` - Prefixed version for compatibility\n  - `no-helpers` - Without helper classes\n  - `no-helpers-prefixed` - Prefixed without helpers\n  - `no-dark-mode` - Without dark mode support  \n    **Default:** `complete`\n- `-i, --icon <library>` - Icon library:\n  - `none` - No icon library\n  - `fontawesome` - Font Awesome\n  - `mdi` - Material Design Icons\n  - `ionicons` - Ionicons\n  - `material-icons` - Material Icons\n  - `material-symbols` - Material Symbols  \n    **Default:** `none`\n- `--skills` / `--no-skills` - Install (or skip) the bestax AI skills into\n  `.claude/skills/` (with a `CLAUDE.md`) so a Claude Code session picks them up\n  automatically. When omitted you're prompted; with `-y` the default is to install.\n- `-y, --yes` - Skip prompts and use defaults or provided options.  \n  When used, the following defaults are selected unless overridden by flags:\n  - Template: `vite`\n  - Bulma flavor: `complete`\n  - Icon library: `none`\n  - AI skills: installed (pass `--no-skills` to opt out)\n\n  `-y` never deletes files. If the target directory is not empty, the run stops, lists what is\n  there, and changes nothing; add `--overwrite` to empty it first. Earlier versions emptied the\n  directory under `-y` alone, so a script that relied on that now needs `--overwrite`.\n\n- `--overwrite` - Remove existing files if the target directory is not empty, without asking.\n  Every other flag is checked first, so a typo stops the run before anything is deleted.\n\n**Example:**\n\n```bash\n# Create a TypeScript project with Font Awesome icons\nnpm create bestax@latest my-app -t vite-ts -i fontawesome -b complete\n\n# Use all defaults (skip prompts)\nnpm create bestax@latest my-app -y\n```\n\n## Templates\n\nAvailable templates:\n\n- `vite` - Vite + JavaScript\n- `vite-ts` - Vite + TypeScript\n\nEach template includes:\n\n- Pre-configured bestax-bulma integration (React 19)\n- The latest `@allxsmith/bestax-bulma`, which ships Bulma v1 automatically\n- Icon library support (Font Awesome, Material Design, etc.)\n- Sample components demonstrating library usage\n- Development and build scripts\n\n## For AI Tools\n\nScaffolding for an AI agent? Pass `--skills` (or accept the prompt) to drop the bestax\nAgent Skills and a `CLAUDE.md` into the new project so Claude Code, Cursor, or Copilot\nbuild the bestax way from the start. The library also ships LLM-optimized docs:\n\n- [LLMs guide](https://bestax.io/docs/guides/llms) — using bestax with Claude Code, Cursor, Copilot\n- [Agent Skills](https://bestax.io/docs/skills/intro) — teach your agent the bestax conventions\n- [llms.txt](https://bestax.io/llms.txt) (curated index) · [llms-full.txt](https://bestax.io/llms-full.txt) (full docs)\n\n## Development\n\n```bash\nnpm run build    # Build the CLI\nnpm run dev      # Watch mode\nnpm test         # Run tests\nnpm run lint     # Lint CLI source code\nnpm run typecheck # Type check CLI source code\n```\n\n**Note on Templates:** Template files in `templates/` are excluded from linting. They should be manually validated by scaffolding a test project and running lint/build there before releasing.\n\n## Hardened by default\n\nA scaffolder runs with write access to your filesystem and picks your starting dependencies, so how it is built and published matters:\n\n- **Signed provenance** — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/create-bestax#provenance), or run `npm audit signatures`.\n- **npm OIDC trusted publishing** — short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed.\n- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`.\n- **Dependencies are a deliberate act** — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.\n- **Every GitHub Action is pinned to a full commit SHA**, so a compromised action release can't roll silently into a build of this CLI.\n- **CodeQL, Dependency Review, and Dependabot** run continuously, alongside a high-severity `pnpm audit` gate.\n- **Layered AI review before merge** — [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.\n\nFull detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)\n\n## Telemetry\n\n`create-bestax` can send one **anonymous** usage event after a successful\nscaffold — only if you opt in when asked (once, at the end of a scaffold). The\nevent is just the choices you made — template, Bulma flavor, icon library,\nskills, package manager — plus the CLI version, Node major version, and OS\nplatform; never names, IPs, machine IDs, paths, or file contents, and no\nidentifier exists that could link two events together. Opt out any time with\n`--no-telemetry`, `BESTAX_TELEMETRY=0`, or `DO_NOT_TRACK=1`.\n\nFull disclosure of every field and control: [Telemetry guide](https://bestax.io/docs/guides/telemetry)\n\n## Publishing\n\nThis package uses semantic-release with scope-based rules. Only commits with `feat(create-bestax)` or `fix(create-bestax)` will trigger releases.\n"
+  "readme": "# create-bestax\n\n[![npm version](https://img.shields.io/npm/v/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![npm downloads](https://img.shields.io/npm/dm/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://badge.socket.dev/npm/package/create-bestax/latest)](https://socket.dev/npm/package/create-bestax/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14361/badge)](https://www.bestpractices.dev/projects/14361)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/create-bestax#provenance)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nThe scaffolder for [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) — spin up a Vite app pre-wired for the **Bulma v1** React component library in one command. Picks your framework (JS or TypeScript), CSS flavor, and icon library, and can drop in the bestax **AI skills** so an agent like Claude Code knows the library from the first prompt.\n\nPart of the [bestax monorepo](https://github.com/allxsmith/bestax) — see also [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) for the components themselves.\n\n## Requirements\n\n- **Node.js 22 or newer.** Node 18 and 20 are both past end-of-life. On an older runtime the\n  CLI exits immediately with an explicit upgrade message.\n- npm 10 or newer (ships with Node 22), or yarn/pnpm.\n\n## Usage\n\n### Quick Start\n\n```bash\n# Using npm\nnpm create bestax@latest my-app\n\n# Using npx\nnpx create-bestax@latest my-app\n```\n\n### Interactive Mode\n\nRunning without arguments will prompt you for all options:\n\n```bash\nnpm create bestax@latest\n```\n\nYou'll be asked to:\n\n1. Enter a project name (and, if that directory already holds files, confirm removing them;\n   nothing is removed until you have answered the last question)\n2. Select a framework (Vite or Vite + TypeScript)\n3. Choose a Bulma CSS flavor (the `--bulma` options below)\n4. Select an icon library (Font Awesome, Material Icons, etc.)\n5. Choose whether to install the bestax AI skills into `.claude/skills/`\n\nEvery prompt has a flag equivalent, so the whole flow is scriptable and CI-friendly — see the options below.\n\n### Command Line Options\n\n```bash\nnpm create bestax@latest [project-directory] -- [options]\n```\n\nPut the options after `--`. npm needs it to pass them on at all, and so does bun, whose\n`bun create` rejects short flags such as `-t` and `-y` itself. pnpm and Yarn 1 accept the options\nwith or without it.\n\n**Arguments:**\n\n- `[project-directory]` - Optional project directory name. It also becomes the `package.json`\n  name, lower-cased the way `npm init` does and without a leading `_`, since npm rejects both.\n\n**Options:**\n\n- `-t, --template <template>` - Template to use: `vite` or `vite-ts`  \n  **Default:** `vite`\n- `-b, --bulma <flavor>` - Bulma CSS flavor:\n  - `complete` - Full Bulma CSS with all components and helpers\n  - `prefixed` - Prefixed version for compatibility\n  - `no-helpers` - Without helper classes\n  - `no-helpers-prefixed` - Prefixed without helpers\n  - `no-dark-mode` - Without dark mode support  \n    **Default:** `complete`\n- `-i, --icon <library>` - Icon library:\n  - `none` - No icon library\n  - `fontawesome` - Font Awesome\n  - `mdi` - Material Design Icons\n  - `ionicons` - Ionicons\n  - `material-icons` - Material Icons\n  - `material-symbols` - Material Symbols  \n    **Default:** `none`\n- `--skills` / `--no-skills` - Install (or skip) the bestax AI skills into\n  `.claude/skills/` (with a `CLAUDE.md`) so a Claude Code session picks them up\n  automatically. When omitted you're prompted; with `-y` the default is to install.\n- `-y, --yes` - Skip prompts and use defaults or provided options.  \n  When used, the following defaults are selected unless overridden by flags:\n  - Template: `vite`\n  - Bulma flavor: `complete`\n  - Icon library: `none`\n  - AI skills: installed (pass `--no-skills` to opt out)\n\n  `-y` never deletes files. If the target directory is not empty, the run stops, lists what is\n  there, and changes nothing; add `--overwrite` to empty it first. Earlier versions emptied the\n  directory under `-y` alone, so a script that relied on that now needs `--overwrite`.\n\n- `--overwrite` - Remove existing files if the target directory is not empty, without asking.\n  Every other flag is checked first, so a typo stops the run before anything is deleted.\n\n**Example:**\n\n```bash\n# Create a TypeScript project with Font Awesome icons\nnpm create bestax@latest my-app -- -t vite-ts -i fontawesome -b complete\n\n# Use all defaults (skip prompts)\nnpm create bestax@latest my-app -- -y\n\n# The same with bun\nbun create bestax@latest my-app -- -y\n```\n\n## Templates\n\nAvailable templates:\n\n- `vite` - Vite + JavaScript\n- `vite-ts` - Vite + TypeScript\n\nEach template includes:\n\n- Pre-configured bestax-bulma integration (React 19)\n- The latest `@allxsmith/bestax-bulma`, which ships Bulma v1 automatically\n- Icon library support (Font Awesome, Material Design, etc.)\n- Sample components demonstrating library usage\n- Development and build scripts\n\n## For AI Tools\n\nScaffolding for an AI agent? Pass `--skills` (or accept the prompt) to drop the bestax\nAgent Skills and a `CLAUDE.md` into the new project so Claude Code, Cursor, or Copilot\nbuild the bestax way from the start. The library also ships LLM-optimized docs:\n\n- [LLMs guide](https://bestax.io/docs/guides/llms) — using bestax with Claude Code, Cursor, Copilot\n- [Agent Skills](https://bestax.io/docs/skills/intro) — teach your agent the bestax conventions\n- [llms.txt](https://bestax.io/llms.txt) (curated index) · [llms-full.txt](https://bestax.io/llms-full.txt) (full docs)\n\n## Development\n\n```bash\nnpm run build    # Build the CLI\nnpm run dev      # Watch mode\nnpm test         # Run tests\nnpm run lint     # Lint CLI source code\nnpm run typecheck # Type check CLI source code\n```\n\n**Note on Templates:** Template files in `templates/` are excluded from linting. They should be manually validated by scaffolding a test project and running lint/build there before releasing.\n\n## Hardened by default\n\nA scaffolder runs with write access to your filesystem and picks your starting dependencies, so how it is built and published matters:\n\n- **Signed provenance** — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/create-bestax#provenance), or run `npm audit signatures`.\n- **npm OIDC trusted publishing** — short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed.\n- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`.\n- **Dependencies are a deliberate act** — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.\n- **Every GitHub Action is pinned to a full commit SHA**, so a compromised action release can't roll silently into a build of this CLI.\n- **CodeQL, Dependency Review, and Dependabot** run continuously, alongside a high-severity `pnpm audit` gate.\n- **Layered AI review before merge** — [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.\n\nFull detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)\n\n## Telemetry\n\n`create-bestax` can send one **anonymous** usage event after a successful\nscaffold — only if you opt in when asked (once, at the end of a scaffold). The\nevent is just the choices you made — template, Bulma flavor, icon library,\nskills, package manager — plus the CLI version, Node major version, and OS\nplatform; never names, IPs, machine IDs, paths, or file contents, and no\nidentifier exists that could link two events together. Opt out any time with\n`--no-telemetry`, `BESTAX_TELEMETRY=0`, or `DO_NOT_TRACK=1`.\n\nFull disclosure of every field and control: [Telemetry guide](https://bestax.io/docs/guides/telemetry)\n\n## Publishing\n\nThis package uses semantic-release with scope-based rules. Only commits with `feat(create-bestax)` or `fix(create-bestax)` will trigger releases.\n"
 }

package/templates/skills/bestax-custom-component/examples/stat-card.tsx

@@ -64,8 +64,8 @@ export function StatCard({
           name={icon}
           size="large"
           textColor={color}
-          // Decorative: the label below already says it, so hide it from AT —
-          // Icon otherwise emits its default aria-label="icon". (To *label* an
+          // Decorative: the label below already says it, so it stays hidden
+          // from AT, as an Icon with no `ariaLabel` is anyway. (To *label* an
           // icon, use Icon's own camelCase `ariaLabel`; most components take
           // the plain aria-label attribute.)
           aria-hidden="true"

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

@@ -131,13 +131,23 @@ The `label` prop on the single-control convenience inputs (`Input`, `Select`, `T
 generated one otherwise, and an explicit `labelProps={{ htmlFor }}` wins. The wiring only
 happens when the component renders its own `Field` (nested inside one, the `label` prop is
 dropped); the date/time pickers skip it in `inline` mode and `Taginput` skips it at
-`maxTags` (no visible input to label). The group inputs (`Checkboxes`, `Radios`, `Rate`,
-`DateRangeInput`) associate their `label` too, but group-style: the wrapper gets `role="group"`/`"radiogroup"`
-and `aria-labelledby` pointing at the label. Composing `Field` + bases yourself also
-associates: `Field`'s own `label` wires to a single composed `InputBase`/`SelectBase`/
-`TextAreaBase` (skipped for `grouped`/`hasAddons`). Pass `labelProps={{ htmlFor }}` plus a
-matching `id` only when you want a stable id, or `labelProps={{ htmlFor: undefined }}` to
-opt out — e.g. when the labeled `Field` wraps something that is not one of those bases.
+`maxTags` (no visible input to label). A `range` `Slider` points the `for` at its low thumb
+and also puts the label at the start of both thumbs' names through `aria-labelledby`
+("Price range Minimum value"). Its `ariaLabel={[low, high]}` replaces those names outright, so
+leave it off when a label already names the Slider. The group inputs (`Checkboxes`, `Radios`, `Rate`,
+`DateRangeInput`) associate their `label` too, but group-style: the wrapper gets
+`role="group"`/`"radiogroup"` and `aria-labelledby` pointing at the label. Composing yourself
+also associates: a labeled `Field` names the one control it holds, whether a composed
+`InputBase`/`SelectBase`/`TextAreaBase` or any input above (through the id), or a group
+(through `aria-labelledby`). Either way, an `aria-label` or `aria-labelledby` you give a
+group wins over the label. A `Checkbox`, `Radio` or `Switch` takes nothing from a `Field`:
+each is named by its own children, so put the text there. The association is skipped for
+`grouped`/`hasAddons`, and a nested `Field` starts its own scope, so a
+horizontal `Field` whose body holds an inner `Field` needs `labelProps={{ htmlFor }}` plus the
+control's `id` (for a group, `labelProps={{ id, htmlFor: undefined }}` plus its
+`aria-labelledby`, since nothing takes the label's `for` there). Pass
+`labelProps={{ htmlFor }}` plus a matching `id` only when you want a stable id, or
+`labelProps={{ htmlFor: undefined }}` to opt out.
 
 ## Convenience vs composed
 

package/templates/skills/bestax-form/references/api.md

@@ -8,16 +8,16 @@ via `useBulmaClasses`.
 
 Container and layout. Compound parts: `Field.Label`, `Field.Body`.
 
-| Prop                    | Type                                              | Notes                                                                                                                                  |
-| ----------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `horizontal`            | `boolean`                                         | Label + control side by side. Auto-wraps children in `Field.Body`.                                                                     |
-| `grouped`               | `boolean \| 'centered' \| 'right' \| 'multiline'` | Controls in a row.                                                                                                                     |
-| `hasAddons`             | `boolean \| 'centered' \| 'right'`                | Attached controls.                                                                                                                     |
-| `narrow`                | `boolean`                                         | Constrain to content width (inside horizontal bodies).                                                                                 |
-| `label`                 | `ReactNode`                                       | Convenience label; auto-associates with a single composed `InputBase`/`SelectBase`/`TextAreaBase` (skipped for `grouped`/`hasAddons`). |
-| `labelSize`             | `'small' \| 'normal' \| 'medium' \| 'large'`      | Label size.                                                                                                                            |
-| `labelProps`            | label attributes                                  | Props for the `<label>`. An explicit `htmlFor` (even `undefined`) takes over the association; otherwise it is set automatically.       |
-| `textColor` / `bgColor` | Bulma color                                       | Helper colors for the field.                                                                                                           |
+| Prop                    | Type                                              | Notes                                                                                                                                                                                              |
+| ----------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `horizontal`            | `boolean`                                         | Label + control side by side. Auto-wraps children in `Field.Body`.                                                                                                                                 |
+| `grouped`               | `boolean \| 'centered' \| 'right' \| 'multiline'` | Controls in a row.                                                                                                                                                                                 |
+| `hasAddons`             | `boolean \| 'centered' \| 'right'`                | Attached controls.                                                                                                                                                                                 |
+| `narrow`                | `boolean`                                         | Constrain to content width (inside horizontal bodies).                                                                                                                                             |
+| `label`                 | `ReactNode`                                       | Names the one control it holds: a composed base or convenience input through its id, a group through `aria-labelledby` (skipped for `grouped`/`hasAddons`; a nested `Field` starts its own scope). |
+| `labelSize`             | `'small' \| 'normal' \| 'medium' \| 'large'`      | Label size.                                                                                                                                                                                        |
+| `labelProps`            | label attributes                                  | Props for the `<label>`. An explicit `htmlFor` (even `undefined`) takes over the association; otherwise it is set automatically. An `id` here is what a group's `aria-labelledby` points at.       |
+| `textColor` / `bgColor` | Bulma color                                       | Helper colors for the field.                                                                                                                                                                       |
 
 ## Control — `form/Control.tsx`
 

package/templates/skills/bestax-form/references/patterns.md

@@ -203,7 +203,15 @@ const [volume, setVolume] = useState(50);
 <Slider value={volume} onChange={setVolume} min={0} max={100} tooltip="auto" />;
 
 const [range, setRange] = useState<[number, number]>([20, 80]);
-<Slider range value={range} onChange={setRange} min={0} max={100} />;
+// The label names both thumbs: "Price range Minimum value" / "... Maximum value".
+<Slider
+  range
+  label="Price range"
+  value={range}
+  onChange={setRange}
+  min={0}
+  max={100}
+/>;
 
 // Numberinput
 const [qty, setQty] = useState(1);

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

@@ -89,16 +89,18 @@ to `iconLeftName`/`iconRightName` if one is given, otherwise leaving the icon co
 
 ## Accessibility
 
-Every `Icon` renders `aria-label` (default `"icon"`), set via its camelCase `ariaLabel` prop.
-Only a few components declare that prop (`Icon`, `Delete`, `Slider`, `Carousel`) — everything
-else takes the standard `aria-label` attribute, e.g. `<Navbar.Burger aria-label="menu" />`.
+An `Icon` is decorative unless it is named: with no `ariaLabel` it renders `aria-hidden="true"`
+and no name. Name it with its camelCase `ariaLabel` prop, and it renders `role="img"` with that
+`aria-label`. Only a few components declare that prop (`Icon`, `Delete`, `Slider`, `Carousel`):
+everything else takes the standard `aria-label` attribute, e.g.
+`<Navbar.Burger aria-label="menu" />`.
 
 - **Meaningful icon** (stands alone, conveys information): pass a descriptive
   `ariaLabel="Delete item"`.
 - **Decorative icon** (next to visible text that says the same thing, e.g. inside `IconText`
-  or a labeled `Button`): hide it from screen readers with `aria-hidden`:
-  `<Icon name="check" aria-hidden="true" />` — otherwise "icon" (or a duplicate label) is
-  announced alongside the text.
+  or a labeled `Button`): leave `ariaLabel` off, and the icon stays out of the accessible
+  name. An explicit `aria-hidden="true"`, as in the examples here, says the same thing.
+- **Icon-only control:** name the control (`<Button aria-label="Delete item">`), not the icon.
 
 ## References
 

package/templates/skills/bestax-icons/examples/icon-usage.tsx

@@ -6,7 +6,6 @@
 // Set the library ONCE on ConfigProvider ('fa' | 'mdi' | 'ion' |
 // 'material-icons' | 'material-symbols' — Ionicons is 'ion', NOT 'ionicons');
 // every <Icon> below then omits `library`.
-import React from 'react';
 import {
   ConfigProvider,
   Icon,
@@ -22,7 +21,7 @@ export function IconShowcase() {
       <Box>
         <Title size="5">Meaningful icons carry their own label</Title>
         {/* Standalone icons convey information — give them a descriptive
-            ariaLabel (the default is just "icon"). */}
+            ariaLabel, which also makes the icon an image. */}
         <Icon
           name="triangle-exclamation"
           textColor="warning"
@@ -34,7 +33,8 @@ export function IconShowcase() {
           Decorative icons hide from screen readers
         </Title>
         {/* Next to visible text the icon repeats the message — aria-hidden
-            stops "icon" (or a duplicate) being announced. */}
+            keeps a duplicate from being announced. An Icon with no ariaLabel
+            renders it anyway; writing it out says so. */}
         <IconText iconProps={{ name: 'star', 'aria-hidden': 'true' }}>
           Starred
         </IconText>

package/templates/skills/bestax-icons/references/icon-libraries.md

@@ -2,7 +2,7 @@
 
 Facts an agent can act on for each of the five libraries `Icon` supports. The library ships no
 icon fonts: the app must install the chosen library (the `npm create bestax` scaffold's
-`--icon` flag does this; in an existing app, follow Setup below).
+`--icon` flag wires it in; in an existing app, follow Setup below).
 
 ## How `Icon` renders
 
@@ -67,8 +67,11 @@ Set it once on `ConfigProvider` and omit `library` everywhere else.
 
 ## Google Material Icons — `'material-icons'`
 
-- **Setup:** `npm install material-icons` and `import 'material-icons';`.
-- **Scaffold flag:** `--icon material-icons`.
+- **Setup:** `npm install material-icons` and `import 'material-icons/iconfont/filled.css';`, the
+  style `Icon` renders by default. Add `outlined.css`, `round.css`, `sharp.css` or `two-tone.css`
+  from `material-icons/iconfont/` for those variants; the bare `import 'material-icons';` loads
+  all five fonts.
+- **Scaffold flag:** `--icon material-icons` (imports `filled.css` only).
 - **Names:** snake_case ligature text: `home`, `rocket_launch`, `shopping_cart`. A kebab-case
   name will not match a ligature and renders as raw text.
 - **Variants:** `filled` (default) / `outlined` / `round` / `sharp` — note **`round`**, not
@@ -77,8 +80,10 @@ Set it once on `ConfigProvider` and omit `library` everywhere else.
 
 ## Material Symbols — `'material-symbols'`
 
-- **Setup:** `npm install material-symbols` and `import 'material-symbols';`.
-- **Scaffold flag:** `--icon material-symbols`.
+- **Setup:** `npm install material-symbols` and `import 'material-symbols/outlined.css';`, the
+  style `Icon` renders by default. Add `rounded.css` or `sharp.css` for those variants; the bare
+  `import 'material-symbols';` loads all three fonts.
+- **Scaffold flag:** `--icon material-symbols` (imports `outlined.css` only).
 - **Names:** snake_case ligature text, same as Material Icons: `rocket_launch`.
 - **Variants:** `outlined` (default) / `rounded` / `sharp` — note **`rounded`** here vs
   Material Icons' `round`.
@@ -126,5 +131,5 @@ Multiple segments via `items`:
 />
 ```
 
-Icons inside `IconText` sit next to their visible text — mark them decorative with
-`aria-hidden` (see SKILL.md's accessibility rules).
+Icons inside `IconText` sit next to their visible text, so leave them decorative: no
+`ariaLabel`, or an explicit `aria-hidden` (see SKILL.md's accessibility rules).

package/templates/skills/bestax-layout-scaffold/examples/app-shell.tsx

@@ -10,7 +10,7 @@
 //
 // `ConfigProvider` wraps the shell once at the root to set the app-wide icon
 // library (so <Icon> needs no `library` prop) and, optionally, a class prefix.
-import React, { useEffect, useState } from 'react';
+import { useEffect, useState } from 'react';
 import {
   ConfigProvider,
   Navbar,

package/templates/skills/bestax-layout-scaffold/examples/card-grid.tsx

@@ -5,7 +5,6 @@
 // it (flexGrow="1"), so short blurbs don't leave ragged card bottoms.
 // (`height: 100%` on the card would NOT work — it resolves against auto
 // height. For uniform grids, Grid/Cell gives equal heights for free.)
-import React from 'react';
 import {
   Section,
   Container,

package/templates/skills/bestax-layout-scaffold/examples/centered.tsx

@@ -1,7 +1,6 @@
 // Centered single-column page — auth, settings, focused forms.
 // A narrow column is centered with `<Columns isCentered>`; on mobile the column
 // becomes full width automatically.
-import React from 'react';
 import {
   Section,
   Container,

package/templates/skills/bestax-layout-scaffold/examples/content-page.tsx

@@ -7,7 +7,6 @@
 //      e.g. mt="4" (1rem) instead of style={{ marginTop: '1rem' }},
 //           textAlign="centered" instead of style={{ textAlign: 'center' }},
 //           textColor="grey" instead of style={{ color: '#…' }}.
-import React from 'react';
 import {
   ConfigProvider,
   Hero,

package/templates/skills/bestax-layout-scaffold/examples/landing.tsx

@@ -10,7 +10,7 @@
 // also needs the `has-navbar-fixed-top` class on <html> so the page is padded
 // below it (never an inline padding offset) — Bulma requires this and the
 // library does NOT add it for you.
-import React, { useEffect, useState } from 'react';
+import { useEffect, useState } from 'react';
 import {
   Navbar,
   Hero,

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

@@ -145,7 +145,8 @@ A `.tabs` converts around its `<ul>`, and the `<li>`s and `<a>`s inside stay as
 renders its own `<a>` with tab roles and puts its label in a `<span>`, so converting the tabs
 themselves is by hand (something that sat beside the text in the `<a>`, a `Tag` say, then wants a
 `Span display="flex" alignItems="center"` around it and the label). A `.icon` converts around the
-`<i>` inside it when it carries an `aria-label`, which `Icon` writes otherwise.
+`<i>` inside it when it carries the attribute `Icon` writes otherwise: `aria-hidden` with no name,
+no `role` and no `tabIndex`, and `role="img"` beside an `aria-label` or `aria-labelledby`.
 
 A `.menu` converts with its `.menu-label`s and `.menu-list`s, and so do the items in a list. An
 item has no class to go by, so the codemod finds it by where it sits: a `<li>` whose nearest
@@ -264,20 +265,20 @@ as `items`.
 
 ```jsx
 <span className="icon-text">
-  <span className="icon" aria-label="Home">
+  <span className="icon" aria-hidden="true">
     <i className="fas fa-home"></i>
   </span>
   <span>Home</span>
 </span>
 // becomes
-<IconText iconProps={{ library: "fa", name: "home", ariaLabel: "Home" }}>Home</IconText>
+<IconText iconProps={{ library: "fa", name: "home", "aria-hidden": "true" }}>Home</IconText>
 ```
 
 The glyph is read from the `<i>`: its Font Awesome style class (`fas`, `far`, `fa-solid`, ...) or
 `mdi`, the one class that names the glyph (`fa-home` as `name: "home"`), and the rest as
 `features`. `library` is always written, so a `ConfigProvider` with another `iconLibrary` doesn't
 change what renders. The `.icon`'s own classes and attributes join the glyph's props as they
-would on `Icon`, with `aria-label` as `ariaLabel`.
+would on `Icon`, under their own names.
 
 It converts only when every `.icon` inside converts to `Icon` on its own and holds a bare, empty
 `<i>` naming a Font Awesome or Material Design Icons glyph, and the only other children are those
@@ -320,6 +321,14 @@ renders `has-text-<color>` too, and so does `is-centered`, which `isCentered` re
 beside `isRight`. Anything else keeps it as markup with a `children:File`, `context:File` or
 `attr` TODO.
 
+A `has-name` `.file` with no `.file-name` converts only with Bulma's `is-empty` written on it as a
+static class, since `File` renders `is-empty` there itself whatever a condition says, so a
+condition on it can't stand in. The class then goes with the rest of the tree. The `File` gets
+`fileName=""`, which pins its name empty the way a `.file-name`'s text pins it to that text. With
+no `fileName`, `File` would show the name of the file a user picks and drop `is-empty`, which the
+markup never does. Without a static `is-empty` the `.file` stays markup with a `defaults:File` TODO
+that names the class to write.
+
 ## Families this source leaves as markup
 
 Their markup doesn't map element by element (the bestax component renders parts of its own, or

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

@@ -76,7 +76,11 @@ attributes you want (usually both, with a real label), then re-run. `Navbar` ren
 `role="navigation"` and `aria-label="main navigation"`, which Bulma's own navbar markup carries;
 give the `<nav>` both, with your own label if you like. `Breadcrumb` renders
 `aria-label="breadcrumbs"`, so give its `<nav>` an `aria-label`, whatever it says.
-`Icon` renders `aria-label="icon"`, so give a `.icon` an `aria-label` that says what the icon means.
+`Icon` hides an icon with no name, no `role` and no `tabIndex`, with `aria-hidden="true"`, and
+makes one named by `aria-label` or `aria-labelledby` an image, with `role="img"`. Give a decorative
+`.icon` `aria-hidden="true"`, and a meaningful one an `aria-label` that says what it means and
+`role="img"`. One whose name is an expression may render with no name, so it needs a `role` of its
+own.
 `Pagination` renders Bulma's own `role="navigation"` and `aria-label="pagination"`, and
 `Pagination.Previous`, `Pagination.Next` and `Pagination.Link` render `tabIndex={0}`, so give each
 element the attribute it's missing.
@@ -84,6 +88,11 @@ element the attribute it's missing.
 sets none, and `Card.Header.Icon` renders `aria-label="more options"` too. One whose `type` isn't
 `button`, `submit` or `reset` gets an `attr:type` TODO instead, since bestax writes `button` in its
 place. Write the type you mean, then re-run.
+`File` renders a class rather than an attribute: Bulma's `is-empty`, on a `has-name` `.file` with
+no `.file-name`, whatever a condition says. Write `is-empty` on the `.file` as a static class, then
+re-run: a condition on `is-empty` can't stand in, so one already there still gets this TODO. The
+`File` it becomes gets `fileName=""`, so a file the user picks leaves it as the markup was: no name
+area, and `is-empty` still on.
 
 ### `drops:<Target>`
 

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

@@ -6,7 +6,7 @@ license: MIT
 
 # Optimizing CSS size with @allxsmith/bestax-bulma
 
-The JS side is tree-shakable (the **entire** library is ~49 KB min+gzip). The stylesheet is
+The JS side is tree-shakable (the **entire** library is ~65 KB min+gzip). The stylesheet is
 not: a prebuilt flavor ships all of Bulma + the bestax extras regardless of which components
 the app renders. Judge stylesheet weight by the **gzipped** transfer size — never the raw
 `dist/` number.
@@ -77,10 +77,14 @@ recommending it, grep the app's source for helper props on bestax components:
 
 ## Lever 2 — modular Sass build
 
-Compile only the Bulma modules + bestax extras partials the app actually uses. Needs the
-`sass` compiler as a dev dependency (Bulma's own build tool — Vite compiles `.scss` natively):
+Compile only the Bulma modules + bestax extras partials the app actually uses. Needs `bulma`
+as a dependency of the app itself (under pnpm, the app's Sass can only load what the app lists)
+and the `sass` compiler as a dev dependency (Bulma's own build tool — Vite compiles `.scss`
+natively):
 
 ```sh
+# with the project's own package manager (pnpm add, yarn add) if it isn't npm
+npm install bulma
 npm install -D sass
 ```
 
@@ -114,9 +118,9 @@ partial inventory, and a worked example are in `references/modular-build.md`.
 
 ## Lever 3 — import & icon-asset hygiene (minor)
 
-- **Named imports.** `import * as Bestax from '@allxsmith/bestax-bulma'` defeats tree
-  shaking. Convert to named imports (`import { Button, Card } from …`) — a JS-side saving
-  (whole library ≈ 49 KB min+gzip), so report it honestly as minor.
+- **Named imports.** Convert `import * as Bestax from '@allxsmith/bestax-bulma'` to named
+  imports (`import { Button, Card } from …`). Any saving is on the JS side, so report it
+  honestly as minor.
 - **Unused icon libraries.** Scaffolded apps may carry an icon library the app never uses:
   icon-font packages in `package.json` (`@fortawesome/fontawesome-free`, `@mdi/font`,
   `material-icons`, `material-symbols`) with their CSS imports in `src/main.*`, or Ionicons

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

@@ -7,11 +7,14 @@ This is the "Option C" pattern from the
 ## Prerequisites
 
 ```sh
+# with the project's own package manager (pnpm add, yarn add) if it isn't npm
+npm install bulma
 npm install -D sass
 ```
 
 `sass` is Bulma's own compiler, dev-only. Vite compiles `.scss` out of the box — no plugin.
-`bulma` is already present as a dependency of `@allxsmith/bestax-bulma`, and the library
+`bulma` has to be a dependency of the app itself: bestax-bulma depends on it, but under pnpm's
+default layout the app's Sass can only load the packages the app lists. The library
 publishes its SCSS sources (`src/scss` ships in the npm package, exposed via the
 `@allxsmith/bestax-bulma/scss/*` export).
 
@@ -150,11 +153,13 @@ not `flexbox` — `flexbox` holds only the alignment props. Verified failure mod
 ## Worked example — the create-bestax starter app
 
 The `npm create bestax` starter renders `Container`, `Section`, `Columns`/`Column`, `Image`,
-`Title`/`SubTitle`, `Box`, `Card`, `Buttons`/`Button`, and `Notification` — all stock Bulma,
-no bestax extras. Its helper props are `display`/`justifyContent` (visibility + flexbox),
-`textAlign` (typography), and `textColor` (color); it uses no spacing props. That inventory
-compiles to the following — verified pixel-equivalent to the prebuilt `complete` flavor in
-headless Chromium (light and dark), at 453 KB raw / 40 KB gzip vs 813 KB / 83 KB:
+`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:
 
 ```scss
 // src/styles.scss
@@ -167,6 +172,7 @@ headless Chromium (light and dark), at 453 KB raw / 40 KB gzip vs 813 KB / 83 KB
 
 @use 'bulma/sass/elements/box';
 @use 'bulma/sass/elements/button'; // Button + Buttons
+@use 'bulma/sass/elements/delete'; // Notification's close button
 @use 'bulma/sass/elements/image';
 @use 'bulma/sass/elements/notification';
 @use 'bulma/sass/elements/title'; // Title + SubTitle
@@ -176,9 +182,8 @@ headless Chromium (light and dark), at 453 KB raw / 40 KB gzip vs 813 KB / 83 KB
 @use 'bulma/sass/layout/section';
 
 @use 'bulma/sass/helpers/visibility'; // display="flex"
-@use 'bulma/sass/helpers/flexbox'; // justifyContent/flexGrow/flexShrink
+@use 'bulma/sass/helpers/flexbox'; // flexGrow
 @use 'bulma/sass/helpers/typography'; // textAlign
-@use 'bulma/sass/helpers/color'; // textColor
 ```
 
 ```tsx

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

@@ -5,7 +5,7 @@
 // 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.
-import React, { useState } from 'react';
+import { useState } from 'react';
 import {
   Theme,
   Box,

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

@@ -6,7 +6,7 @@
 // palette. The <Theme> component writes those CSS variables for you:
 //   - isRoot          -> inject the variables globally at :root (use once, at the app root)
 //   - without isRoot  -> wrap children in a <div> and scope the variables to it
-import React from 'react';
+import type { ReactNode } from 'react';
 import {
   Theme,
   Button,
@@ -17,7 +17,7 @@ import {
 
 // 1) Global brand theme at the app root.
 //    Hue is unitless; saturation and lightness are percentages.
-export function ThemedApp({ children }: { children: React.ReactNode }) {
+export function ThemedApp({ children }: { children: ReactNode }) {
   return (
     <Theme
       isRoot

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

@@ -246,7 +246,9 @@ list it, so set it in your CSS or through a `style` prop.)
 The two `range` variables paint a range calendar (`DateRangeInput`): the band between a range's
 ends, and the fainter band shown while the end is still being picked. Both are mixed from
 `--bulma-dateinput-cell-selected-bg`, so `color` and an override of the selected fill re-tint
-them too.
+them too. Inside a band, a nearby month's day reads `--bulma-dateinput-cell-color` rather than
+`--bulma-dateinput-cell-other-month-color`, and today's tint leans a fifth of the way toward
+`--bulma-text-strong`, so both stay readable on the band's color.
 
 ### DateRangeInput
 

package/templates/vite/README.md

@@ -6,15 +6,15 @@ This template provides a minimal setup to get React working in Vite with HMR and
 
 ```bash
 pnpm install
-pnpm dev
+pnpm run dev
 ```
 
 ## Available Scripts
 
-- `pnpm dev` - Start development server
-- `pnpm build` - Build for production
-- `pnpm preview` - Preview production build
-- `pnpm lint` - Run ESLint
+- `pnpm run dev` - Start development server
+- `pnpm run build` - Build for production
+- `pnpm run preview` - Preview production build
+- `pnpm run lint` - Run ESLint
 
 ## Features
 
@@ -22,7 +22,6 @@ pnpm dev
 - 🎨 Bulma CSS framework
 - 📦 bestax-bulma component library
 - 🔧 ESLint pre-configured
-- 🎯 Font Awesome icons included
 
 ## Learn More
 

package/templates/vite/src/App.css

@@ -1 +1,14 @@
-/* App-specific styles - keep minimal, let Bulma handle the styling */
+/* App-specific styles - keep minimal, let Bulma handle the styling */
+
+/* A link inside running text needs more than its color to stand out
+   (WCAG 1.4.1), and no helper prop sets an underline. */
+.text-link {
+  text-decoration: underline;
+}
+
+/* Bulma spaces a notification from whatever follows it in the same parent,
+   and each notification here is alone in its status region, so the space
+   between two showing at once goes between their regions instead. */
+.status-region:not(:empty) + .status-region:not(:empty) {
+  margin-top: var(--bulma-block-spacing);
+}