create-bestax 3.3.3 → 3.5.0

package/dist/constants.d.ts

@@ -22,8 +22,9 @@ export declare const MESSAGES: {
     readonly PROJECT_CREATED: "✔ Done! Project created successfully.";
     readonly NEXT_STEPS: "Next steps:";
     readonly HAPPY_CODING: "Happy coding! 🎉";
-    readonly SKILLS_ADDED: "✔ Installed bestax AI skills into .claude/skills/ (+ CLAUDE.md)";
+    readonly SKILLS_ADDED: "✔ Installed bestax AI skills into .claude/skills/ (+ CLAUDE.md, .claude/launch.json)";
 };
+export declare const LAUNCH_JSON: string;
 export declare const PROMPTS: {
     readonly PROJECT_NAME: "Project name:";
     readonly SELECT_FRAMEWORK: "Select a framework:";

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,SAAS,EAAE,QAAQ,EAG/B,CAAC;AAEF,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AACpD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAEtD,eAAO,MAAM,QAAQ;;;;;;;wCAaQ,MAAM;uCAEP,MAAM;sCACP,MAAM;4CAEA,MAAM;;;;;CAM7B,CAAC;AAEX,eAAO,MAAM,OAAO;;;;;;CAOV,CAAC;AAOX,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAK9D,CAAC;AAKF,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,SAAS,GACpB,aAAa,MAAM,EACnB,8BAA8B,eAAe,KAC5C,MA+DF,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IAIrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,cAAc,EAAE,WAAW,EA6CvC,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EA4CtC,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,SAAS,EAAE,QAAQ,EAG/B,CAAC;AAEF,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AACpD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAEtD,eAAO,MAAM,QAAQ;;;;;;;wCAaQ,MAAM;uCAEP,MAAM;sCACP,MAAM;4CAEA,MAAM;;;;;CAM7B,CAAC;AASX,eAAO,MAAM,WAAW,QAed,CAAC;AAEX,eAAO,MAAM,OAAO;;;;;;CAOV,CAAC;AAOX,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAK9D,CAAC;AAKF,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,SAAS,GACpB,aAAa,MAAM,EACnB,8BAA8B,eAAe,KAC5C,MAoEF,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IAIrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,cAAc,EAAE,WAAW,EA6CvC,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EA4CtC,CAAC"}

package/dist/constants.js

@@ -23,8 +23,26 @@ export const MESSAGES = {
     PROJECT_CREATED: '✔ Done! Project created successfully.',
     NEXT_STEPS: 'Next steps:',
     HAPPY_CODING: 'Happy coding! 🎉',
-    SKILLS_ADDED: '✔ Installed bestax AI skills into .claude/skills/ (+ CLAUDE.md)',
+    SKILLS_ADDED: '✔ Installed bestax AI skills into .claude/skills/ (+ CLAUDE.md, .claude/launch.json)',
 };
+// Dev-server manifest written into .claude/ with the skills opt-in so Claude
+// Code's browser preview (`preview_start`) can boot the app by name instead of
+// rediscovering the dev command from package.json. `npm` is deliberately
+// package-manager-neutral (`npm run dev` works whichever PM installed the
+// project), and `--strictPort` stops Vite from silently auto-incrementing to
+// 5174 when 5173 is busy — a mismatch with the declared `port` must fail
+// loudly, not point the preview at nothing.
+export const LAUNCH_JSON = JSON.stringify({
+    version: '0.0.1',
+    configurations: [
+        {
+            name: 'dev',
+            runtimeExecutable: 'npm',
+            runtimeArgs: ['run', 'dev', '--', '--strictPort'],
+            port: 5173,
+        },
+    ],
+}, null, 2) + '\n';
 export const PROMPTS = {
     PROJECT_NAME: 'Project name:',
     SELECT_FRAMEWORK: 'Select a framework:',
@@ -93,9 +111,14 @@ automatically when the task matches:
 - **bestax-theming** — colors, branding, and dark mode via the \`Theme\` component (\`colorMode\`).
 - **bestax-layout-scaffold** — scaffold full pages (app shell, landing, centered, card grid).
 - **bestax-icons** — icons via \`Icon\`/\`IconText\`: library setup, name formats, variants, a11y.
+- **bestax-optimize** — shrink the built CSS: measure raw+gzip, then flavor switch or a modular Sass build.
 
 Prefer the library's components and these skills over hand-written Bulma markup or custom CSS.
 
+\`.claude/launch.json\` declares this app's dev server for Claude Code's browser preview
+(\`npm run dev\` on port 5173, \`--strictPort\`) — start it from there rather than rediscovering
+the command.
+
 ## Docs
 
 - Docs site: https://bestax.io

package/dist/project-creator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-creator.d.ts","sourceRoot":"","sources":["../src/project-creator.ts"],"names":[],"mappings":"AA2BA,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAIxB,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,YAAY,CAAS;gBAEjB,YAAY,CAAC,EAAE,MAAM;IAI3B,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa3D,sBAAsB,CAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;IAkBnB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAInC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC;IAiBV,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmDhB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,YAAY;IAYd,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAgJV,mBAAmB,CACvB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmEV,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAwIvE"}
+{"version":3,"file":"project-creator.d.ts","sourceRoot":"","sources":["../src/project-creator.ts"],"names":[],"mappings":"AA2BA,OAAO,EAOL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAIxB,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,YAAY,CAAS;gBAEjB,YAAY,CAAC,EAAE,MAAM;IAI3B,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa3D,sBAAsB,CAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;IAkBnB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAInC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC;IAqBV,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmDhB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,YAAY;IAYd,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAgJV,mBAAmB,CACvB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmEV,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAwIvE"}

package/dist/project-creator.js

@@ -6,7 +6,7 @@ import { checkDirectoryExists, isDirectoryEmpty, emptyDirectory, ensureDirectory
 import { promptProjectName, promptOverwriteDirectory, promptTemplate, promptIconLibrary, promptBulmaFlavor, promptInstallSkills, } from './prompts.js';
 import { displayHeader, displaySuccess, displayError, displayCancelled, } from './display.js';
 import { validateProjectName } from './validators.js';
-import { MESSAGES, ICON_LIBRARIES, BULMA_FLAVORS, CLAUDE_MD, CONFIG_PROVIDER_ICON_VALUES, } from './constants.js';
+import { MESSAGES, ICON_LIBRARIES, BULMA_FLAVORS, CLAUDE_MD, LAUNCH_JSON, CONFIG_PROVIDER_ICON_VALUES, } from './constants.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export class ProjectCreator {
     templatesDir;
@@ -52,6 +52,7 @@ export class ProjectCreator {
             return;
         }
         await fs.copy(skillsSrc, path.join(targetPath, '.claude', 'skills'));
+        await fs.writeFile(path.join(targetPath, '.claude', 'launch.json'), LAUNCH_JSON);
         await fs.writeFile(path.join(targetPath, 'CLAUDE.md'), CLAUDE_MD(projectName, options));
         console.log(chalk.green(MESSAGES.SKILLS_ADDED));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bestax",
-  "version": "3.3.3",
+  "version": "3.5.0",
   "description": "Create a new bestax-bulma project",
   "type": "module",
   "bin": {

package/templates/skills/bestax-custom-component/references/component-catalog.md

@@ -14,8 +14,8 @@ instead of hand-writing markup.
   (`m`/`p` spacing, `textColor`/`bgColor`, `textAlign`, `display`, flex, …) —
   documented once in `references/api.md`.
 - **Compound components** expose sub-parts via dot access (e.g. `Card.Header`,
-  `Navbar.Item`, `Tabs.Tab`, `Hero.Body`); see the component's linked page for the
-  full set.
+  `Navbar.Item`, `Tabs.Tab`, `Hero.Body`, `Columns.Column`, `Table.Tr`); see the
+  component's linked page for the full set.
 - Raw `*Base` form exports (`InputBase`, `SelectBase`, `TextAreaBase`, …) are
   escape-hatch variants of the convenience wrappers above them; see the Form docs.
 

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

@@ -91,7 +91,8 @@ Every component also accepts the shared Bulma helper props (`m`/`p` spacing, `te
 
 ## Columns / Column
 
-The responsive grid. `Columns` is the row; `Column` is a cell.
+The responsive grid. `Columns` is the row; `Column` is a cell (also reachable as
+`Columns.Column`).
 
 **Columns**
 
@@ -156,7 +157,7 @@ the column's auto height). Make the `Column` a flex container and let the card g
 
 ## Grid / Cell
 
-Bulma's CSS Grid. **Preferred for uniform grids** — same-shaped items in a repeating pattern
+Bulma's CSS Grid (`Cell` is also reachable as `Grid.Cell`). **Preferred for uniform grids** — same-shaped items in a repeating pattern
 (card grids, galleries, dashboards): CSS Grid gives **equal-height cells for free** (per row —
 each row's cells match its tallest), with no flex recipe needed. Reach for `Columns`/`Column` instead when you need proportional or
 per-breakpoint column _sizes_ (a 2/3 + 1/3 split, different counts per breakpoint).

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

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

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

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