create-bestax 4.2.13 → 4.2.15

package/README.md

@@ -29,9 +29,6 @@ npm create bestax@latest my-app
 
 # Using npx
 npx create-bestax@latest my-app
-
-# Alternative naming
-npm create bestax-bulma@latest my-app
 ```
 
 ### Interactive Mode
@@ -47,7 +44,7 @@ You'll be asked to:
 1. Enter a project name (and, if that directory already holds files, confirm removing them;
    nothing is removed until you have answered the last question)
 2. Select a framework (Vite or Vite + TypeScript)
-3. Choose a Bulma CSS flavor (Complete or Minimal)
+3. Choose a Bulma CSS flavor (the `--bulma` options below)
 4. Select an icon library (Font Awesome, Material Icons, etc.)
 5. Choose whether to install the bestax AI skills into `.claude/skills/`
 
@@ -56,9 +53,13 @@ Every prompt has a flag equivalent, so the whole flow is scriptable and CI-frien
 ### Command Line Options
 
 ```bash
-npm create bestax@latest [project-directory] [options]
+npm create bestax@latest [project-directory] -- [options]
 ```
 
+Put the options after `--`. npm needs it to pass them on at all, and so does bun, whose
+`bun create` rejects short flags such as `-t` and `-y` itself. pnpm and Yarn 1 accept the options
+with or without it.
+
 **Arguments:**
 
 - `[project-directory]` - Optional project directory name. It also becomes the `package.json`
@@ -104,10 +105,13 @@ npm create bestax@latest [project-directory] [options]
 
 ```bash
 # Create a TypeScript project with Font Awesome icons
-npm create bestax@latest my-app -t vite-ts -i fontawesome -b complete
+npm create bestax@latest my-app -- -t vite-ts -i fontawesome -b complete
 
 # Use all defaults (skip prompts)
-npm create bestax@latest my-app -y
+npm create bestax@latest my-app -- -y
+
+# The same with bun
+bun create bestax@latest my-app -- -y
 ```
 
 ## Templates

package/dist/cli.d.ts

@@ -16,5 +16,15 @@ export declare function copyTemplate(templatePath: string, targetPath: string):
 export declare function createProject(projectDir?: string, options?: CLIOptions): Promise<void>;
 export declare function createCLI(): Command;
 export declare function isMainModule(importMetaUrl: string, argv1: string): boolean;
-export declare function runCLI(): Promise<void>;
+/**
+ * pnpm, bun and bunx hand a `--` to the scaffolder as it was typed, where npm
+ * and Yarn 1 strip it, so `pnpm create bestax my-app -- -t vite-ts` arrives as
+ * `my-app -- -t vite-ts`. Commander reads `--` as the end of the options, and
+ * every flag after it became an extra argument: "too many arguments" (#950).
+ * Bun users need that `--`, because `bun create` rejects short flags such as
+ * `-t` and `-y` itself. So the first `--` after the script path is dropped
+ * before parsing, and a second keeps its usual meaning.
+ */
+export declare function dropForwardedSeparator(argv: readonly string[]): string[];
+export declare function runCLI(argv?: readonly string[]): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EACL,cAAc,EACd,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1E,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACtE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGzE,OAAO,EAAE,cAAc,EAAE,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,cAAc,IAAI,cAAc,EAChC,iBAAiB,IAAI,iBAAiB,EACtC,iBAAiB,IAAI,iBAAiB,GACvC,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,wBAAsB,cAAc,CAClC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC,CAGhC;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,aAAa,CACjC,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,IAAI,CAAC,CAGf;AAcD,wBAAgB,SAAS,IAAI,OAAO,CAsCnC;AAED,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAG5C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EACL,cAAc,EACd,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1E,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACtE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGzE,OAAO,EAAE,cAAc,EAAE,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,cAAc,IAAI,cAAc,EAChC,iBAAiB,IAAI,iBAAiB,EACtC,iBAAiB,IAAI,iBAAiB,GACvC,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,wBAAsB,cAAc,CAClC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC,CAGhC;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,aAAa,CACjC,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,IAAI,CAAC,CAGf;AAcD,wBAAgB,SAAS,IAAI,OAAO,CAsCnC;AAED,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAKxE;AAED,wBAAsB,MAAM,CAC1B,IAAI,GAAE,SAAS,MAAM,EAAiB,GACrC,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/cli.js

@@ -71,9 +71,24 @@ export function createCLI() {
 export function isMainModule(importMetaUrl, argv1) {
     return importMetaUrl === `file://${argv1}`;
 }
-export async function runCLI() {
+/**
+ * pnpm, bun and bunx hand a `--` to the scaffolder as it was typed, where npm
+ * and Yarn 1 strip it, so `pnpm create bestax my-app -- -t vite-ts` arrives as
+ * `my-app -- -t vite-ts`. Commander reads `--` as the end of the options, and
+ * every flag after it became an extra argument: "too many arguments" (#950).
+ * Bun users need that `--`, because `bun create` rejects short flags such as
+ * `-t` and `-y` itself. So the first `--` after the script path is dropped
+ * before parsing, and a second keeps its usual meaning.
+ */
+export function dropForwardedSeparator(argv) {
+    const separator = argv.indexOf('--', 2);
+    return separator === -1
+        ? [...argv]
+        : [...argv.slice(0, separator), ...argv.slice(separator + 1)];
+}
+export async function runCLI(argv = process.argv) {
     const program = createCLI();
-    await program.parseAsync();
+    await program.parseAsync(dropForwardedSeparator(argv));
 }
 // Only run if this is the main module
 /* istanbul ignore next */

package/dist/constants.d.ts

@@ -66,6 +66,15 @@ export interface BulmaFlavor {
     color: typeof chalk.yellow;
     importStatement: string;
     needsPrefix?: boolean;
+    noHelpers?: boolean;
 }
 export declare const BULMA_FLAVORS: BulmaFlavor[];
+export declare const CSS_ORDER_COMMENT: string;
+export interface StarterClass {
+    prop: string;
+    className: string;
+    declaration: string;
+}
+export declare const NO_HELPERS_STARTER_CLASSES: StarterClass[];
+export declare const NO_HELPERS_APP_CSS: string;
 //# sourceMappingURL=constants.d.ts.map

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;AAGtD,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAOpC,eAAO,MAAM,QAAQ;;;;;;6CASa,MAAM;;;wCAQX,MAAM,WAAW,MAAM,EAAE;oCAE7B,MAAM;gDAIM,MAAM,WAAW,MAAM,EAAE;uCAIlC,MAAM;sCACP,MAAM;4CAEA,MAAM;;;;;wCAMV,MAAM,mBAAmB,MAAM;;;;;CAclD,CAAC;AASX,eAAO,MAAM,WAAW,QAed,CAAC;AAEX,eAAO,MAAM,OAAO;;;;;;;CAQV,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,MAmIF,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;AAGtD,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAOpC,eAAO,MAAM,QAAQ;;;;;;6CASa,MAAM;;;wCAQX,MAAM,WAAW,MAAM,EAAE;oCAE7B,MAAM;gDAIM,MAAM,WAAW,MAAM,EAAE;uCAIlC,MAAM;sCACP,MAAM;4CAEA,MAAM;;;;;wCAMV,MAAM,mBAAmB,MAAM;;;;;CAclD,CAAC;AASX,eAAO,MAAM,WAAW,QAed,CAAC;AAEX,eAAO,MAAM,OAAO;;;;;;;CAQV,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;AAkCD,eAAO,MAAM,SAAS,GACpB,aAAa,MAAM,EACnB,8BAA8B,eAAe,KAC5C,MA8HF,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;IAGzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,cAAc,EAAE,WAAW,EA8DvC,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;IAGtB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EA8CtC,CAAC;AAKF,eAAO,MAAM,iBAAiB,QAE+B,CAAC;AAE9D,MAAM,WAAW,YAAY;IAE3B,IAAI,EAAE,MAAM,CAAC;IAEb,SAAS,EAAE,MAAM,CAAC;IAElB,WAAW,EAAE,MAAM,CAAC;CACrB;AAOD,eAAO,MAAM,0BAA0B,EAAE,YAAY,EAgBpD,CAAC;AAEF,eAAO,MAAM,kBAAkB,QAMjB,CAAC"}

package/dist/constants.js

@@ -87,6 +87,36 @@ export const CONFIG_PROVIDER_ICON_VALUES = {
     'material-icons': 'material-icons',
     'material-symbols': 'material-symbols',
 };
+// The house style opens with the inline-style table for a flavor that has the
+// helper classes, and with the named-class rule for one that does not.
+const HELPER_HOUSE_STYLE = `**Never inline \`style={{}}\`** — the components accept helper props that cover the common
+cases. Before writing \`style\`, translate each declaration with this table:
+
+| Inline style you're about to write         | Helper props instead                                                                                                                       |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| \`marginTop: '1rem'\` (any margin/padding) | \`mt="4"\` — \`m\`/\`mt\`/\`mx\`/\`p\`/\`py\`/… scale: \`1\`=0.25rem, \`2\`=0.5rem, \`3\`=0.75rem, \`4\`=1rem, \`5\`=1.5rem, \`6\`=3rem (nearest step) |
+| \`textAlign: 'center'\`                    | \`textAlign="centered"\` (also \`left\`, \`right\`, \`justified\`)                                                                          |
+| \`color: '#…'\`                            | \`textColor\` with the nearest Bulma color: \`primary\`, \`link\`, \`info\`, \`success\`, \`warning\`, \`danger\`, \`white\`, \`black\`, \`grey\` (+ \`grey-light\`, \`grey-dark\`, …) |
+| \`backgroundColor: '#…'\`                  | \`bgColor\` (same palette)                                                                                                                  |
+| \`fontSize: …\`                            | \`textSize="1"\`…\`"7"\` (\`1\` largest) — for headings use \`Title\`/\`SubTitle\` \`size\`                                                 |
+| \`fontWeight: …\`                          | \`textWeight\`: \`light\`, \`normal\`, \`medium\`, \`semibold\`, \`bold\`                                                                   |
+| \`textTransform\`, italics                 | \`textTransform\`: \`uppercase\`, \`lowercase\`, \`capitalized\`, \`italic\`                                                                |
+| \`display: 'flex'\` + flex properties      | same-named props: \`display="flex"\`, \`flexDirection\`, \`justifyContent\`, \`alignItems\`, \`flexWrap\`                                   |
+| \`height: '100%'\` on a flex child         | \`flexGrow="1"\`                                                                                                                            |
+| \`display: 'none'\`                        | \`visibility="hidden"\`, or responsive \`display*\` props (\`displayMobile\`, \`displayTablet\`, …)                                         |
+| \`gap: '1rem'\` (flex or grid)             | \`gap="2"\`, or one axis: \`columnGap\`, \`rowGap\`; gap scale: \`1\`=0.5rem, \`2\`=1rem, \`4\`=2rem, half steps (\`"1.5"\`)               |
+
+- Spacing, typography, and flex helpers are on every component; \`textColor\`/\`bgColor\` are
+  on the content components (\`Box\`, \`Block\`, \`Title\`, \`Content\`, \`Hero\`, \`Card\`, …) — the
+  ones with a semantic \`color\` variant (\`Tag\`, \`Tabs\`, \`Panel\`) take \`color\` instead.
+  \`Notification\` is the mixed case: it takes \`textColor\`, but its background comes from
+  the semantic \`color\` prop, not \`bgColor\`.
+- No helper matches (e.g. \`maxWidth\`, a one-off gradient)? Add a named class to
+  \`src/App.css\` and pass it via \`className\` — still never inline \`style\`.`;
+const NO_HELPERS_HOUSE_STYLE = `**Never inline \`style={{}}\`**, and don't reach for helper props in its place either:
+this app's flavor leaves out Bulma's helper classes, so \`mt="4"\`, \`textAlign="centered"\` and \`flexGrow="1"\`
+render nothing. Write a named class in \`src/App.css\`, which loads after Bulma's CSS, and pass it via \`className\`.
+`;
 export const CLAUDE_MD = (projectName, { bulmaFlavor, iconLibrary }) => {
     const flavor = BULMA_FLAVORS.find(f => f.name === bulmaFlavor);
     const icon = ICON_LIBRARIES.find(lib => lib.name === iconLibrary);
@@ -99,6 +129,13 @@ export const CLAUDE_MD = (projectName, { bulmaFlavor, iconLibrary }) => {
         setupLines.push(`- Every Bulma class carries the \`bestax-\` prefix and the app is wrapped in ` +
             `\`<ConfigProvider classPrefix="bestax-">\` — custom CSS selectors must match the prefix.`);
     }
+    if (flavor?.noHelpers) {
+        setupLines.push(`- This flavor leaves out Bulma's helper classes, so **helper props that add those classes render nothing**: ` +
+            `\`mt\`, \`gap\`, \`textAlign\`, \`textColor\`, \`display\` and \`flexGrow\` still add ` +
+            `class names, but no rule matches them. \`skeleton\` still works, because the flavor keeps ` +
+            `Bulma's skeleton styles. The starter page lays itself out with named classes in ` +
+            `\`src/App.css\` instead.`);
+    }
     const providerIconValue = CONFIG_PROVIDER_ICON_VALUES[iconLibrary];
     setupLines.push(iconLibrary === 'none'
         ? `- No icon library is installed — add one before using \`<Icon>\` ` +
@@ -107,7 +144,17 @@ export const CLAUDE_MD = (projectName, { bulmaFlavor, iconLibrary }) => {
             (providerIconValue
                 ? ` The app is already wrapped in \`<ConfigProvider iconLibrary="${providerIconValue}">\` ` +
                     `— extend that provider rather than adding a second one.`
-                : ''));
+                : '') +
+            (icon?.setupInstructions ? ` ${icon.setupInstructions}` : ''));
+    const houseStyleOpening = flavor?.noHelpers
+        ? NO_HELPERS_HOUSE_STYLE
+        : HELPER_HOUSE_STYLE;
+    // The wrapper elements are only a way out where their helper props render.
+    const utilityClassRule = flavor?.noHelpers
+        ? `- Don't hand-write Bulma utility classes either: this flavor doesn't ship them, so a
+  \`has-text-…\` class renders nothing, and the named class above is what works.`
+        : `- Don't hand-write Bulma utility classes either — bare text/markup has wrapper elements that
+  take the same helper props: \`Span\`, \`Paragraph\`, \`Strong\`, not \`<span className="has-text-…">\`.`;
     return `# ${projectName}
 
 This app is built with [\`@allxsmith/bestax-bulma\`](https://bestax.io) — React components for
@@ -119,36 +166,12 @@ ${setupLines.join('\n')}
 
 ## House style
 
-**Never inline \`style={{}}\`** — the components accept helper props that cover the common
-cases. Before writing \`style\`, translate each declaration with this table:
-
-| Inline style you're about to write         | Helper props instead                                                                                                                       |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| \`marginTop: '1rem'\` (any margin/padding) | \`mt="4"\` — \`m\`/\`mt\`/\`mx\`/\`p\`/\`py\`/… scale: \`1\`=0.25rem, \`2\`=0.5rem, \`3\`=0.75rem, \`4\`=1rem, \`5\`=1.5rem, \`6\`=3rem (nearest step) |
-| \`textAlign: 'center'\`                    | \`textAlign="centered"\` (also \`left\`, \`right\`, \`justified\`)                                                                          |
-| \`color: '#…'\`                            | \`textColor\` with the nearest Bulma color: \`primary\`, \`link\`, \`info\`, \`success\`, \`warning\`, \`danger\`, \`white\`, \`black\`, \`grey\` (+ \`grey-light\`, \`grey-dark\`, …) |
-| \`backgroundColor: '#…'\`                  | \`bgColor\` (same palette)                                                                                                                  |
-| \`fontSize: …\`                            | \`textSize="1"\`…\`"7"\` (\`1\` largest) — for headings use \`Title\`/\`SubTitle\` \`size\`                                                 |
-| \`fontWeight: …\`                          | \`textWeight\`: \`light\`, \`normal\`, \`medium\`, \`semibold\`, \`bold\`                                                                   |
-| \`textTransform\`, italics                 | \`textTransform\`: \`uppercase\`, \`lowercase\`, \`capitalized\`, \`italic\`                                                                |
-| \`display: 'flex'\` + flex properties      | same-named props: \`display="flex"\`, \`flexDirection\`, \`justifyContent\`, \`alignItems\`, \`flexWrap\`                                   |
-| \`height: '100%'\` on a flex child         | \`flexGrow="1"\`                                                                                                                            |
-| \`display: 'none'\`                        | \`visibility="hidden"\`, or responsive \`display*\` props (\`displayMobile\`, \`displayTablet\`, …)                                         |
-| \`gap: '1rem'\` (flex or grid)             | \`gap="2"\`, or one axis: \`columnGap\`, \`rowGap\`; gap scale: \`1\`=0.5rem, \`2\`=1rem, \`4\`=2rem, half steps (\`"1.5"\`)               |
-
-- Spacing, typography, and flex helpers are on every component; \`textColor\`/\`bgColor\` are
-  on the content components (\`Box\`, \`Block\`, \`Title\`, \`Content\`, \`Hero\`, \`Card\`, …) — the
-  ones with a semantic \`color\` variant (\`Tag\`, \`Tabs\`, \`Panel\`) take \`color\` instead.
-  \`Notification\` is the mixed case: it takes \`textColor\`, but its background comes from
-  the semantic \`color\` prop, not \`bgColor\`.
-- No helper matches (e.g. \`maxWidth\`, a one-off gradient)? Add a named class to
-  \`src/App.css\` and pass it via \`className\` — still never inline \`style\`.
-- Don't hand-write Bulma utility classes either — bare text/markup has wrapper elements that
-  take the same helper props: \`Span\`, \`Paragraph\`, \`Strong\`, not \`<span className="has-text-…">\`.
+${houseStyleOpening}
+${utilityClassRule}
   The one exception: companion classes Bulma requires on \`<html>\`/\`<body>\` (e.g.
   \`has-navbar-fixed-top\` with \`Navbar fixed="top"\`) are hand-added in \`index.html\` — no
   component renders those elements.
-- Compound sub-parts (\`Card.*\`, \`Modal.*\`, \`Tabs.*\`, \`Message.*\`) take \`className\` + HTML
+- Compound sub-parts (\`Modal.*\`, \`Tabs.*\`, \`Message.*\`) take \`className\` + HTML
   attributes and their own few props — no Bulma helper props, no \`as\`/\`href\`: nest a
   \`Link\`/\`Span\` inside instead. \`Tabs.Tab\` and \`Tabs.Content.Item\` each require \`index={i}\`,
   and \`Tabs.Tab\` has built-in \`icon\`/\`disabled\` props — no nested \`Icon\` needed.
@@ -250,15 +273,30 @@ export const ICON_LIBRARIES = [
         color: chalk.yellow,
         packageName: 'material-icons',
         packageVersion: '^1.13.14',
-        importStatement: "import 'material-icons';",
+        // The package's bare import puts the filled, outlined, round, sharp and
+        // two-tone fonts into the build. Filled is the style Icon renders by
+        // default, so it is the only one imported.
+        importStatement: "import 'material-icons/iconfont/filled.css';",
+        setupInstructions: 'Only the filled style is loaded (`material-icons/iconfont/filled.css`, the variant `<Icon>` ' +
+            'uses by default). Import `outlined.css`, `round.css`, `sharp.css` or `two-tone.css` from ' +
+            '`material-icons/iconfont/` in `src/main.*` before using those variants.',
     },
     {
         name: 'material-symbols',
         display: 'Material Symbols',
         color: chalk.magenta,
         packageName: 'material-symbols',
-        packageVersion: '^0.45.2',
-        importStatement: "import 'material-symbols';",
+        // 0.x, so the caret holds the minor: this follows the newest minor
+        // bestax-bulma's material-symbols peer range admits, not the newest
+        // published one, or npm refuses the install as a peer conflict.
+        packageVersion: '^0.46.0',
+        // The package's bare import puts the outlined, rounded and sharp fonts
+        // into the build. Outlined is the style Icon renders by default, so it is
+        // the only one imported.
+        importStatement: "import 'material-symbols/outlined.css';",
+        setupInstructions: 'Only the outlined style is loaded (`material-symbols/outlined.css`, the variant `<Icon>` ' +
+            'uses by default). Import `material-symbols/rounded.css` or `sharp.css` in `src/main.*` ' +
+            'before using `variant="rounded"` or `"sharp"`.',
     },
 ];
 export const BULMA_FLAVORS = [
@@ -283,6 +321,7 @@ export const BULMA_FLAVORS = [
         description: 'Core components only, no utility classes — helper props need them (~67 KB gzip)',
         color: chalk.yellow,
         importStatement: "import '@allxsmith/bestax-bulma/versions/bestax-no-helpers.css';",
+        noHelpers: true,
     },
     {
         name: 'no-helpers-prefixed',
@@ -291,6 +330,7 @@ export const BULMA_FLAVORS = [
         color: chalk.magenta,
         importStatement: "import '@allxsmith/bestax-bulma/versions/bestax-no-helpers-prefixed.css';",
         needsPrefix: true,
+        noHelpers: true,
     },
     {
         name: 'no-dark-mode',
@@ -300,3 +340,34 @@ export const BULMA_FLAVORS = [
         importStatement: "import '@allxsmith/bestax-bulma/versions/bestax-no-dark-mode.css';",
     },
 ];
+// Sits above the stylesheet import in the templates' entry files, and the
+// scaffolder writes it back when it swaps in a flavor's stylesheet, so the
+// reason for the import order survives. The no-helpers classes depend on it.
+export const CSS_ORDER_COMMENT = "// Bestax's stylesheet loads before the app's own CSS, so a named class in\n" +
+    '// src/App.css wins over a Bulma rule of the same weight.';
+// Every helper prop the starter App uses, with the named class that stands in
+// for it under a `noHelpers` flavor, where the prop would render nothing. The
+// scaffolder swaps each prop for its class and writes the rules into
+// src/App.css, so the starter keeps its layout and shows that flavor's way of
+// styling. A helper prop added to the starter needs a row here.
+export const NO_HELPERS_STARTER_CLASSES = [
+    {
+        prop: 'textAlign="centered"',
+        className: 'page-title',
+        declaration: 'text-align: center;',
+    },
+    {
+        prop: 'display="flex"',
+        className: 'card-column',
+        declaration: 'display: flex;',
+    },
+    {
+        prop: 'flexGrow="1"',
+        className: 'card-fill',
+        declaration: 'flex-grow: 1;',
+    },
+];
+export const NO_HELPERS_APP_CSS = '\n/* This flavor of Bulma leaves out the helper classes, so helper props such\n' +
+    '   as textAlign and flexGrow render nothing here. Named classes like these do\n' +
+    '   the job instead: write one, then pass it with className. */\n' +
+    NO_HELPERS_STARTER_CLASSES.map(({ className, declaration }) => `.${className} {\n  ${declaration}\n}\n`).join('\n');

package/dist/index.js

@@ -14,6 +14,6 @@ if (majorVersion < MINIMUM_NODE_VERSION) {
         `Please upgrade your Node.js version.`);
     process.exit(1);
 }
-const { createCLI } = await import('./cli.js');
-await createCLI().parseAsync(process.argv);
+const { runCLI } = await import('./cli.js');
+await runCLI();
 export {};

package/dist/project-creator.d.ts

@@ -42,9 +42,28 @@ export declare class ProjectCreator {
     getTemplatePath(template: string): string;
     copyTemplate(template: string, targetPath: string): Promise<void>;
     updateIndexHtmlTitle(targetPath: string, projectName: string): Promise<void>;
+    /**
+     * The template README is written with pnpm commands and lists no icon
+     * library. Rewrite the commands for the package manager that ran the CLI
+     * (the one the success message names too) and list the icon library the
+     * user picked, if any.
+     */
+    updateReadme(targetPath: string, iconLibrary: string): Promise<void>;
     setupSkills(targetPath: string, projectName: string, options: ClaudeMdOptions): Promise<void>;
     setupBulmaFlavor(targetPath: string, bulmaFlavor: string, template: string): Promise<void>;
+    /**
+     * A flavor without Bulma's helper classes leaves the starter's helper props
+     * rendering nothing, so its title loses its centering and its cards their
+     * equal heights. Swap each prop for the named class in
+     * NO_HELPERS_STARTER_CLASSES and append the classes' rules to src/App.css.
+     */
+    replaceStarterHelperProps(targetPath: string, template: string): Promise<void>;
     private getIconName;
+    /**
+     * The `iconProps` entries for a starter card icon. Decorative, since the
+     * card title beside it says the same thing, so it is hidden from screen
+     * readers rather than announced as "icon".
+     */
     private getIconProps;
     setupIconLibrary(targetPath: string, iconLibrary: string, template: string): Promise<void>;
     setupConfigProvider(targetPath: string, bulmaFlavor: string, iconLibrary: string, template: string): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"project-creator.d.ts","sourceRoot":"","sources":["../src/project-creator.ts"],"names":[],"mappings":"AA8BA,OAAO,EAQL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAWxB,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,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,CAAC;AAEnE,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;IAajE;;;;;;;OAOG;IACG,sBAAsB,CAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,qBAAqB,CAAC;IA2BjC;;;OAGG;IACH,eAAe,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI;IAmBpD,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAInC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,oBAAoB,CACxB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAgBV,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;IA4JV,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;IAmItE;;;;;;;;OAQG;YACW,eAAe;CA2B9B"}
+{"version":3,"file":"project-creator.d.ts","sourceRoot":"","sources":["../src/project-creator.ts"],"names":[],"mappings":"AA8BA,OAAO,EAWL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAYxB,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,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,CAAC;AAEnE,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;IAajE;;;;;;;OAOG;IACG,sBAAsB,CAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,qBAAqB,CAAC;IA2BjC;;;OAGG;IACH,eAAe,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI;IAmBpD,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAInC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,oBAAoB,CACxB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAgBhB;;;;;OAKG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBpE,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;IAyDhB;;;;;OAKG;IACG,yBAAyB,CAC7B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmBhB,OAAO,CAAC,WAAW;IA2BnB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAcd,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAsJV,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;IAoItE;;;;;;;;OAQG;YACW,eAAe;CA2B9B"}

package/dist/project-creator.js

@@ -7,7 +7,8 @@ import { promptProjectName, promptOverwriteDirectory, promptTemplate, promptIcon
 import { reportScaffold } from './telemetry.js';
 import { displayHeader, displaySuccess, displayError, displayCancelled, } from './display.js';
 import { validateProjectName, toValidPackageName } from './validators.js';
-import { MESSAGES, TEMPLATES, ICON_LIBRARIES, BULMA_FLAVORS, CLAUDE_MD, LAUNCH_JSON, CONFIG_PROVIDER_ICON_VALUES, } from './constants.js';
+import { MESSAGES, TEMPLATES, ICON_LIBRARIES, BULMA_FLAVORS, CLAUDE_MD, LAUNCH_JSON, CONFIG_PROVIDER_ICON_VALUES, NO_HELPERS_STARTER_CLASSES, NO_HELPERS_APP_CSS, CSS_ORDER_COMMENT, } from './constants.js';
+import { detectPackageManager } from './package-manager.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // npm strips literal `.gitignore` files from published tarballs, so the
 // templates track `_gitignore` instead and the scaffolder renames it back
@@ -100,6 +101,25 @@ export class ProjectCreator {
             await fs.writeFile(indexHtmlPath, updated);
         }
     }
+    /**
+     * The template README is written with pnpm commands and lists no icon
+     * library. Rewrite the commands for the package manager that ran the CLI
+     * (the one the success message names too) and list the icon library the
+     * user picked, if any.
+     */
+    async updateReadme(targetPath, iconLibrary) {
+        const readmePath = path.join(targetPath, 'README.md');
+        if (!fs.existsSync(readmePath))
+            return;
+        const pm = detectPackageManager();
+        let readme = await fs.readFile(readmePath, 'utf8');
+        readme = readme.replace(/\bpnpm (install|run)\b/g, `${pm} $1`);
+        const library = ICON_LIBRARIES.find(lib => lib.name === iconLibrary);
+        if (library && iconLibrary !== 'none') {
+            readme = readme.replace(/^(- .*bestax-bulma component library)$/m, `$1\n- 🎯 ${library.display} icons`);
+        }
+        await fs.writeFile(readmePath, readme);
+    }
     async setupSkills(targetPath, projectName, options) {
         const skillsSrc = path.join(this.templatesDir, 'skills');
         if (!(await checkDirectoryExists(skillsSrc))) {
@@ -122,11 +142,13 @@ export class ProjectCreator {
         const mainFilePath = path.join(targetPath, 'src', mainFileName);
         if (fs.existsSync(mainFilePath)) {
             let content = await fs.readFile(mainFilePath, 'utf8');
-            // Replace the default bestax CSS import with the selected flavor
-            const bestaxImportRegex = /\/\/.*\n\s*import\s+['"]@allxsmith\/bestax-bulma\/bestax\.css['"]\s*;?/;
+            // Replace the default bestax CSS import, and the comment block directly
+            // above it, with the selected flavor's import under the comment that
+            // says why the stylesheets load before the app's own CSS.
+            const bestaxImportRegex = /(?:[ \t]*\/\/[^\n]*\n)+[ \t]*import\s+['"]@allxsmith\/bestax-bulma\/bestax\.css['"]\s*;?/;
             const bestaxImportSimpleRegex = /import\s+['"]@allxsmith\/bestax-bulma\/bestax\.css['"]\s*;?/;
             if (bestaxImportRegex.test(content)) {
-                content = content.replace(bestaxImportRegex, '// Import CSS\n' + flavor.importStatement);
+                content = content.replace(bestaxImportRegex, CSS_ORDER_COMMENT + '\n' + flavor.importStatement);
             }
             else if (bestaxImportSimpleRegex.test(content)) {
                 content = content.replace(bestaxImportSimpleRegex, flavor.importStatement);
@@ -145,6 +167,29 @@ export class ProjectCreator {
             }
             await fs.writeFile(mainFilePath, content);
         }
+        if (flavor.noHelpers) {
+            await this.replaceStarterHelperProps(targetPath, template);
+        }
+    }
+    /**
+     * A flavor without Bulma's helper classes leaves the starter's helper props
+     * rendering nothing, so its title loses its centering and its cards their
+     * equal heights. Swap each prop for the named class in
+     * NO_HELPERS_STARTER_CLASSES and append the classes' rules to src/App.css.
+     */
+    async replaceStarterHelperProps(targetPath, template) {
+        const appFileName = template.includes('-ts') ? 'App.tsx' : 'App.jsx';
+        const appFilePath = path.join(targetPath, 'src', appFileName);
+        const appCssPath = path.join(targetPath, 'src', 'App.css');
+        if (!fs.existsSync(appFilePath) || !fs.existsSync(appCssPath))
+            return;
+        let appContent = await fs.readFile(appFilePath, 'utf8');
+        for (const { prop, className } of NO_HELPERS_STARTER_CLASSES) {
+            appContent = appContent.split(prop).join(`className="${className}"`);
+        }
+        await fs.writeFile(appFilePath, appContent);
+        const css = await fs.readFile(appCssPath, 'utf8');
+        await fs.writeFile(appCssPath, css.replace(/\n*$/, '\n') + NO_HELPERS_APP_CSS);
     }
     getIconName(iconLibrary, iconType) {
         const iconMappings = {
@@ -168,13 +213,20 @@ export class ProjectCreator {
         };
         return iconMappings[iconLibrary]?.[iconType] || '';
     }
+    /**
+     * The `iconProps` entries for a starter card icon. Decorative, since the
+     * card title beside it says the same thing, so it is hidden from screen
+     * readers rather than announced as "icon".
+     */
     getIconProps(iconLibrary, iconType) {
         const iconName = this.getIconName(iconLibrary, iconType);
         if (!iconName)
-            return '';
-        return iconLibrary === 'fontawesome'
-            ? `name="${iconName}" variant="solid"`
-            : `name="${iconName}"`;
+            return [];
+        return [
+            `name: '${iconName}'`,
+            ...(iconLibrary === 'fontawesome' ? [`variant: 'solid'`] : []),
+            `'aria-hidden': 'true'`,
+        ];
     }
     async setupIconLibrary(targetPath, iconLibrary, template) {
         if (iconLibrary === 'none')
@@ -251,48 +303,48 @@ export class ProjectCreator {
                 }
             }
         }
-        // Now add Icon components to App.jsx/App.tsx (for all icon libraries)
+        // Now add an icon to each card title in App.jsx/App.tsx (for all icon
+        // libraries). IconText spaces the icon from its text with Bulma's own
+        // .icon-text rule rather than a margin helper, so the gap holds in the
+        // no-helpers flavors too.
         const isTypeScript = template.includes('-ts');
         const appFileName = isTypeScript ? 'App.tsx' : 'App.jsx';
         const appFilePath = path.join(targetPath, 'src', appFileName);
         if (fs.existsSync(appFilePath)) {
             let appContent = await fs.readFile(appFilePath, 'utf8');
-            // Add Icon import to the bestax-bulma imports
+            // Add IconText to the bestax-bulma imports
             const bulmaImportRegex = /(import\s+\{[\s\S]*?)(}\s+from\s+['"]@allxsmith\/bestax-bulma['"])/;
-            if (bulmaImportRegex.test(appContent) && !appContent.includes('Icon')) {
-                // Check if the import ends with a comma or not
+            if (bulmaImportRegex.test(appContent) &&
+                !/\bIconText\b/.test(appContent)) {
                 const importMatch = appContent.match(bulmaImportRegex);
                 if (importMatch) {
                     const beforeClosingBrace = importMatch[1];
-                    // Remove any trailing comma and whitespace, then add Icon properly
+                    // Remove any trailing comma and whitespace, then add IconText properly
                     const cleanedImport = beforeClosingBrace.replace(/,?\s*$/, '');
-                    appContent = appContent.replace(bulmaImportRegex, cleanedImport + ',\n  Icon$2');
+                    appContent = appContent.replace(bulmaImportRegex, cleanedImport + ',\n  IconText,\n$2');
                 }
             }
-            // Add icon examples in the Cards section
-            // Find the Quick Start Card and add an icon
-            const quickStartRegex = /(Card\.Header\.Title>\s*Quick Start\s*<\/Card\.Header\.Title>)/;
-            if (quickStartRegex.test(appContent)) {
-                const iconProps = this.getIconProps(iconLibrary, 'rocket');
-                if (iconProps) {
-                    appContent = appContent.replace(quickStartRegex, `Card.Header.Title>\n                          <Icon ${iconProps} size="small" mr="2" />\n                          Quick Start\n                        </Card.Header.Title>`);
-                }
-            }
-            // Add icon to Documentation Card
-            const docsRegex = /(Card\.Header\.Title>\s*Documentation\s*<\/Card\.Header\.Title>)/;
-            if (docsRegex.test(appContent)) {
-                const iconProps = this.getIconProps(iconLibrary, 'book');
-                if (iconProps) {
-                    appContent = appContent.replace(docsRegex, `Card.Header.Title>\n                          <Icon ${iconProps} size="small" mr="2" />\n                          Documentation\n                        </Card.Header.Title>`);
-                }
-            }
-            // Add icon to Examples Card
-            const examplesRegex = /(Card\.Header\.Title>\s*Examples\s*<\/Card\.Header\.Title>)/;
-            if (examplesRegex.test(appContent)) {
-                const iconProps = this.getIconProps(iconLibrary, 'code');
-                if (iconProps) {
-                    appContent = appContent.replace(examplesRegex, `Card.Header.Title>\n                          <Icon ${iconProps} size="small" mr="2" />\n                          Examples\n                        </Card.Header.Title>`);
-                }
+            const cardIcons = [
+                ['rocket', 'Quick Start'],
+                ['book', 'Documentation'],
+                ['code', 'Examples'],
+            ];
+            for (const [iconType, title] of cardIcons) {
+                const iconProps = this.getIconProps(iconLibrary, iconType);
+                if (iconProps.length === 0)
+                    continue;
+                const titleRegex = new RegExp(`^([ \\t]*)(<Card\\.Header\\.Title[^>]*>)\\s*${title}\\s*(</Card\\.Header\\.Title>)`, 'm');
+                appContent = appContent.replace(titleRegex, (_match, indent, open, close) => [
+                    `${indent}${open}`,
+                    `${indent}  <IconText`,
+                    `${indent}    iconProps={{`,
+                    ...iconProps.map(entry => `${indent}      ${entry},`),
+                    `${indent}    }}`,
+                    `${indent}  >`,
+                    `${indent}    ${title}`,
+                    `${indent}  </IconText>`,
+                    `${indent}${close}`,
+                ].join('\n'));
             }
             await fs.writeFile(appFilePath, appContent);
         }
@@ -444,6 +496,7 @@ export class ProjectCreator {
             await this.copyTemplate(template, targetPath);
             await updatePackageJson(targetPath, packageName);
             await this.updateIndexHtmlTitle(targetPath, projectName);
+            await this.updateReadme(targetPath, iconLibrary);
             await this.setupBulmaFlavor(targetPath, bulmaFlavor, template);
             await this.setupIconLibrary(targetPath, iconLibrary, template);
             await this.setupConfigProvider(targetPath, bulmaFlavor, iconLibrary, template);