create-bestax 3.3.0 → 3.3.2

package/dist/constants.d.ts

@@ -12,6 +12,7 @@ export declare const MESSAGES: {
     readonly PROJECT_NAME_REQUIRED: "Project name is required";
     readonly PROJECT_NAME_TOO_LONG: "Project name too long";
     readonly PROJECT_NAME_INVALID_CHARS: "Project name can only contain letters, numbers, dots, dashes and underscores";
+    readonly PROJECT_NAME_DOT: "Project name cannot start with a dot (names like \".\" or \"..\" would scaffold outside a new directory) — pass a directory name";
     readonly OPERATION_CANCELLED: "✖ Operation cancelled";
     readonly NO_TTY: string;
     readonly DIRECTORY_NOT_EMPTY: (dir: string) => string;
@@ -41,6 +42,7 @@ export interface IconLibrary {
     display: string;
     color: typeof chalk.yellow;
     packageName?: string;
+    packageVersion?: string;
     importStatement?: string;
     setupInstructions?: string;
 }

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;;;;;;wCAWQ,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;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,cAAc,EAAE,WAAW,EAyCvC,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,EA0CtC,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;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"}

package/dist/constants.js

@@ -10,6 +10,7 @@ export const MESSAGES = {
     PROJECT_NAME_REQUIRED: 'Project name is required',
     PROJECT_NAME_TOO_LONG: 'Project name too long',
     PROJECT_NAME_INVALID_CHARS: 'Project name can only contain letters, numbers, dots, dashes and underscores',
+    PROJECT_NAME_DOT: 'Project name cannot start with a dot (names like "." or ".." would scaffold outside a new directory) — pass a directory name',
     OPERATION_CANCELLED: '✖ Operation cancelled',
     NO_TTY: 'No interactive terminal detected — cannot prompt for input.\n' +
         'Re-run non-interactively with a project name and flags, e.g.:\n' +
@@ -113,6 +114,7 @@ export const ICON_LIBRARIES = [
         display: 'Font Awesome',
         color: chalk.blue,
         packageName: '@fortawesome/fontawesome-free',
+        packageVersion: '^7.2.0',
         importStatement: "import '@fortawesome/fontawesome-free/css/all.min.css';",
     },
     {
@@ -120,6 +122,7 @@ export const ICON_LIBRARIES = [
         display: 'Material Design Icons',
         color: chalk.cyan,
         packageName: '@mdi/font',
+        packageVersion: '^7.4.47',
         importStatement: "import '@mdi/font/css/materialdesignicons.min.css';",
     },
     {
@@ -134,6 +137,7 @@ export const ICON_LIBRARIES = [
         display: 'Google Material Icons',
         color: chalk.yellow,
         packageName: 'material-icons',
+        packageVersion: '^1.13.14',
         importStatement: "import 'material-icons';",
     },
     {
@@ -141,6 +145,7 @@ export const ICON_LIBRARIES = [
         display: 'Material Symbols',
         color: chalk.magenta,
         packageName: 'material-symbols',
+        packageVersion: '^0.45.2',
         importStatement: "import 'material-symbols';",
     },
 ];
@@ -148,14 +153,14 @@ export const BULMA_FLAVORS = [
     {
         name: 'complete',
         display: 'Complete (Recommended)',
-        description: 'Full Bulma CSS with all components and helpers',
+        description: 'Full Bulma CSS with all components and helpers (~82 KB gzip)',
         color: chalk.green,
         importStatement: "import '@allxsmith/bestax-bulma/bestax.css';",
     },
     {
         name: 'prefixed',
         display: 'Prefixed',
-        description: 'All classes prefixed with "bestax-" to avoid conflicts',
+        description: 'All classes prefixed with "bestax-" to avoid conflicts (~84 KB gzip)',
         color: chalk.blue,
         importStatement: "import '@allxsmith/bestax-bulma/versions/bestax-prefixed.css';",
         needsPrefix: true,
@@ -163,14 +168,14 @@ export const BULMA_FLAVORS = [
     {
         name: 'no-helpers',
         display: 'No Helpers',
-        description: 'Core components only, no utility classes',
+        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';",
     },
     {
         name: 'no-helpers-prefixed',
         display: 'No Helpers, Prefixed',
-        description: 'Core components only with "bestax-" prefix',
+        description: 'Core components only with "bestax-" prefix (~69 KB gzip)',
         color: chalk.magenta,
         importStatement: "import '@allxsmith/bestax-bulma/versions/bestax-no-helpers-prefixed.css';",
         needsPrefix: true,
@@ -178,7 +183,7 @@ export const BULMA_FLAVORS = [
     {
         name: 'no-dark-mode',
         display: 'No Dark Mode',
-        description: 'Light mode only, smaller bundle size',
+        description: 'Light mode only, smaller bundle size (~70 KB gzip)',
         color: chalk.cyan,
         importStatement: "import '@allxsmith/bestax-bulma/versions/bestax-no-dark-mode.css';",
     },

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;IA2IV,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,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"}

package/dist/project-creator.js

@@ -135,6 +135,10 @@ export class ProjectCreator {
                 const headEndMatch = htmlContent.match(/<\/head>/);
                 if (headEndMatch) {
                     const insertPosition = headEndMatch.index;
+                    // The ionicons version is pinned to an immutable unpkg URL. SRI
+                    // integrity attributes are deliberately not added: the ionicons ESM
+                    // loader dynamically imports per-icon chunks that cannot carry
+                    // integrity hashes, so entry-file SRI would give false assurance.
                     const ioniconScripts = `    <!-- Ionicons -->
     <script type="module" src="https://unpkg.com/ionicons@8.0.13/dist/ionicons/ionicons.esm.js"></script>
     <script nomodule src="https://unpkg.com/ionicons@8.0.13/dist/ionicons/ionicons.js"></script>
@@ -159,7 +163,8 @@ export class ProjectCreator {
                     packageJson.dependencies = {};
                 }
                 if (library.packageName) {
-                    packageJson.dependencies[library.packageName] = 'latest';
+                    packageJson.dependencies[library.packageName] =
+                        library.packageVersion ?? 'latest';
                 }
                 await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
                 // Add import statement to main file

package/dist/validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"AAMA,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAcnE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD"}
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"AAMA,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAqBnE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD"}

package/dist/validators.js

@@ -6,6 +6,12 @@ export function validateProjectName(value) {
     if (value.length > MAX_PROJECT_NAME_LENGTH) {
         return MESSAGES.PROJECT_NAME_TOO_LONG;
     }
+    // The regex below allows dots, so "." and ".." would pass and resolve to
+    // the current/parent directory — which --yes would then empty. Rejecting
+    // every leading-dot name closes that hole ("/" and "\" are already blocked).
+    if (value.startsWith('.')) {
+        return MESSAGES.PROJECT_NAME_DOT;
+    }
     if (!PROJECT_NAME_REGEX.test(value)) {
         return MESSAGES.PROJECT_NAME_INVALID_CHARS;
     }

package/package.json

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

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

@@ -0,0 +1,78 @@
+---
+name: bestax-icons
+description: Use icons in an app built with @allxsmith/bestax-bulma — the Icon/IconText components and the five supported libraries (Font Awesome, Material Design Icons, Ionicons, Google Material Icons, Material Symbols). Use when adding an icon, choosing or configuring the app-wide icon library, fixing an icon that renders blank, pairing icons with text, or making icons accessible (decorative vs labeled).
+license: MIT
+---
+
+# Icons with @allxsmith/bestax-bulma
+
+`Icon` renders a Bulma icon container (`span.icon`) around a glyph from any of five icon
+libraries behind one normalized API. `IconText` pairs icons with text. The library ships **no
+icon fonts** — the chosen library's package (or CDN script) must be installed in the app.
+
+## Quick start
+
+```tsx
+import { ConfigProvider, Icon, IconText } from '@allxsmith/bestax-bulma';
+
+// Set the library ONCE at the app root; <Icon> then never needs `library`.
+<ConfigProvider iconLibrary="fa">
+  <App />
+</ConfigProvider>;
+
+// Inside the app:
+<Icon name="rocket" ariaLabel="Launch" />;
+<IconText iconProps={{ name: 'star', 'aria-hidden': 'true' }}>
+  Starred
+</IconText>;
+```
+
+## The five libraries
+
+| Library                | `iconLibrary` / `library` value | Name format                  | Example `name`  |
+| ---------------------- | ------------------------------- | ---------------------------- | --------------- |
+| Font Awesome (default) | `'fa'`                          | kebab-case, no `fa-` prefix  | `rocket`        |
+| Material Design Icons  | `'mdi'`                         | kebab-case, no `mdi-` prefix | `rocket-launch` |
+| Ionicons               | `'ion'`                         | kebab-case                   | `rocket`        |
+| Google Material Icons  | `'material-icons'`              | snake_case (a text ligature) | `rocket_launch` |
+| Material Symbols       | `'material-symbols'`            | snake_case (a text ligature) | `rocket_launch` |
+
+⚠️ **The Ionicons value is `'ion'`, not `'ionicons'`.** The `npm create bestax` scaffold's
+`--icon ionicons` flag maps to `iconLibrary="ion"` — passing `'ionicons'` to `ConfigProvider`
+or `library` silently renders nothing.
+
+**The same glyph has a different name per library** (`rocket` vs `rocket-launch` vs
+`rocket_launch`). When an icon renders blank, the name format for the active library is the
+first thing to check. A redundant `fa-`/`mdi-` prefix in `name` is tolerated (stripped), but
+don't rely on it.
+
+## Styling
+
+- `size` — `'small' | 'medium' | 'large'` sizes the Bulma **container** (`is-small` ≈ 1rem,
+  `is-medium` ≈ 2rem, `is-large` ≈ 3rem box). To scale the **glyph**, use `features`
+  (Font Awesome `'fa-lg'`/`'fa-2x'`) or a Bulma text-size class (`'is-size-3'`).
+- `variant` — per-library style: Font Awesome `solid` (default) / `regular` / `brands` /
+  `light` / `duotone` / `thin`; Material Icons `filled` (default) / `outlined` / `round` /
+  `sharp`; Material Symbols `outlined` (default) / `rounded` / `sharp`; Ionicons `outline` /
+  `sharp`. MDI has no variants. Note Material **Icons** uses `round`, Material **Symbols**
+  uses `rounded`.
+- `features` — extra library classes, string or array: `'fa-spin'`, `['fa-lg', 'fa-border']`.
+- Color via the helper props: `textColor="primary"`, `textColor="danger"`, etc.
+
+## Accessibility
+
+Every `Icon` renders `aria-label` (default `"icon"`).
+
+- **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.
+
+## References
+
+- `references/icon-libraries.md` — per-library setup (install/import/CDN), the full
+  name-format and variant tables, `features` values, and the blank-icon troubleshooting list.
+- `examples/icon-usage.tsx` — runnable example: ConfigProvider setup, sizes, variants,
+  colors, IconText, and decorative-vs-labeled patterns.

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

@@ -0,0 +1,80 @@
+// Icons with @allxsmith/bestax-bulma — the canonical patterns.
+//
+// The app must load the icon library itself (bestax ships no icon fonts):
+// here Font Awesome, via `npm install @fortawesome/fontawesome-free` and
+// `import '@fortawesome/fontawesome-free/css/all.min.css';` in main.tsx.
+// 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,
+  IconText,
+  Button,
+  Box,
+  Title,
+} from '@allxsmith/bestax-bulma';
+
+export function IconShowcase() {
+  return (
+    <ConfigProvider iconLibrary="fa">
+      <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"). */}
+        <Icon
+          name="triangle-exclamation"
+          textColor="warning"
+          ariaLabel="Warning"
+        />
+        <Icon name="circle-check" textColor="success" ariaLabel="Success" />
+
+        <Title size="5" mt="4">
+          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. */}
+        <IconText iconProps={{ name: 'star', 'aria-hidden': 'true' }}>
+          Starred
+        </IconText>
+        <Button color="primary">
+          <Icon name="floppy-disk" aria-hidden="true" />
+          <span>Save</span>
+        </Button>
+
+        <Title size="5" mt="4">
+          Sizes, variants, features, color
+        </Title>
+        {/* `size` sizes the Bulma container; `features` scales the glyph. */}
+        <Icon name="rocket" size="large" features="fa-2x" ariaLabel="Launch" />
+        {/* Font Awesome styles come from `variant`; brands require it. */}
+        <Icon name="bell" variant="regular" ariaLabel="Notifications" />
+        <Icon name="github" variant="brands" ariaLabel="GitHub" />
+        {/* Spin + color via features and the textColor helper. */}
+        <Icon
+          name="spinner"
+          features="fa-spin"
+          textColor="info"
+          ariaLabel="Loading"
+        />
+
+        <Title size="5" mt="4">
+          Multi-segment icon text
+        </Title>
+        <IconText
+          items={[
+            {
+              iconProps: { name: 'train', 'aria-hidden': 'true' },
+              text: 'Metro',
+            },
+            {
+              iconProps: { name: 'arrow-right', 'aria-hidden': 'true' },
+              text: 'Airport',
+            },
+          ]}
+        />
+      </Box>
+    </ConfigProvider>
+  );
+}

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

@@ -0,0 +1,131 @@
+# Icon libraries — setup, names, variants, troubleshooting
+
+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).
+
+## How `Icon` renders
+
+- `fa` / `mdi` — an `<i>` with CSS classes (`fas fa-rocket`, `mdi mdi-rocket-launch`).
+- `material-icons` / `material-symbols` — an `<i>` whose **text content** is the name
+  (a font ligature): `<i class="material-icons">rocket_launch</i>`. That's why these names are
+  snake_case — they are literal text, not class names.
+- `ion` — the `<ion-icon>` web component: `<ion-icon name="rocket-outline" />`.
+
+The resolution order for the library is `library` prop → `ConfigProvider iconLibrary` → `'fa'`.
+Set it once on `ConfigProvider` and omit `library` everywhere else.
+
+## Font Awesome — `'fa'` (the default)
+
+- **Setup:** `npm install @fortawesome/fontawesome-free` and
+  `import '@fortawesome/fontawesome-free/css/all.min.css';` once (e.g. `main.tsx`).
+- **Scaffold flag:** `--icon fontawesome`.
+- **Names:** kebab-case without the `fa-` prefix: `rocket`, `circle-check`, `magnifying-glass`.
+  A leading `fa-` in `name` is stripped automatically (so `fa-rocket` also works), but write
+  the bare name.
+- **Variants** (`variant` → class): `solid` → `fas` (default), `regular` → `far`, `brands` →
+  `fab`, `light` → `fal`, `duotone` → `fad`, `thin` → `fat`. The free package includes only
+  solid, regular (partial), and brands — light/duotone/thin need a Font Awesome Pro kit.
+- **Features:** Font Awesome utility classes — `'fa-lg'`, `'fa-2x'`…`'fa-10x'`, `'fa-spin'`,
+  `'fa-pulse'`, `'fa-border'`, `'fa-fw'`, `'fa-flip-horizontal'`, `'fa-rotate-90'`.
+- Brand icons **require** `variant="brands"`: `<Icon name="github" variant="brands" />`.
+
+## Material Design Icons — `'mdi'`
+
+- **Setup:** `npm install @mdi/font` and
+  `import '@mdi/font/css/materialdesignicons.min.css';`.
+- **Scaffold flag:** `--icon mdi`.
+- **Names:** kebab-case without the `mdi-` prefix: `account`, `rocket-launch`,
+  `home-outline`. A leading `mdi-` is stripped automatically. Outline/off styles are part of
+  the **name** (`home-outline`, `bell-off`), not a variant.
+- **Variants:** none — `variant` is ignored for MDI.
+- **Features:** MDI helpers (`'mdi-24px'`, `'mdi-48px'`, `'mdi-spin'`, `'mdi-rotate-90'`) or
+  Bulma text-size classes (`'is-size-3'`).
+
+## Ionicons — `'ion'` ⚠️ value is `ion`, not `ionicons`
+
+- **Setup:** a CDN script pair in `index.html` (no npm package — it registers the
+  `<ion-icon>` web component):
+
+  ```html
+  <script
+    type="module"
+    src="https://unpkg.com/ionicons@8.0.13/dist/ionicons/ionicons.esm.js"
+  ></script>
+  <script
+    nomodule
+    src="https://unpkg.com/ionicons@8.0.13/dist/ionicons/ionicons.js"
+  ></script>
+  ```
+
+- **Scaffold flag:** `--icon ionicons` — which maps to `iconLibrary="ion"`. Passing
+  `'ionicons'` as the `library`/`iconLibrary` value renders nothing.
+- **Names:** kebab-case: `rocket`, `heart`, `settings`.
+- **Variants:** `outline` and `sharp` — appended to the name (`variant="outline"` +
+  `name="heart"` renders `<ion-icon name="heart-outline">`). Omit for the filled default.
+- **Features:** not applicable (web component, not classes); size the container with `size`
+  or style via CSS.
+
+## Google Material Icons — `'material-icons'`
+
+- **Setup:** `npm install material-icons` and `import 'material-icons';`.
+- **Scaffold flag:** `--icon material-icons`.
+- **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
+  `rounded`.
+- **Features:** Bulma classes like `'is-size-1'` (the font scales with text size).
+
+## Material Symbols — `'material-symbols'`
+
+- **Setup:** `npm install material-symbols` and `import 'material-symbols';`.
+- **Scaffold flag:** `--icon material-symbols`.
+- **Names:** snake_case ligature text, same as Material Icons: `rocket_launch`.
+- **Variants:** `outlined` (default) / `rounded` / `sharp` — note **`rounded`** here vs
+  Material Icons' `round`.
+- **Features:** Bulma classes like `'is-size-1'`.
+
+## One glyph, five names
+
+| Glyph    | fa                 | mdi             | ion        | material-icons / material-symbols |
+| -------- | ------------------ | --------------- | ---------- | --------------------------------- |
+| Rocket   | `rocket`           | `rocket-launch` | `rocket`   | `rocket_launch`                   |
+| Home     | `house` / `home`   | `home`          | `home`     | `home`                            |
+| Settings | `gear`             | `cog`           | `settings` | `settings`                        |
+| Search   | `magnifying-glass` | `magnify`       | `search`   | `search`                          |
+
+## Blank icon? Check in this order
+
+1. **Library value** — `'ion'` not `'ionicons'`; the five valid values are `fa`, `mdi`,
+   `ion`, `material-icons`, `material-symbols`.
+2. **Name format for that library** — kebab vs snake_case (see the table above); for
+   material-* a wrong name renders as literal text instead of a glyph.
+3. **The library's CSS/script is actually loaded** — the import in `main.tsx` (or the
+   Ionicons scripts in `index.html`) must exist; bestax ships none of them.
+4. **Variant availability** — Font Awesome free has no `light`/`duotone`/`thin`; brand
+   glyphs need `variant="brands"`.
+
+## IconText
+
+Pairs icon(s) with text inside a Bulma `icon-text` container. Single icon:
+
+```tsx
+<IconText iconProps={{ name: 'check', 'aria-hidden': 'true' }}>Saved</IconText>
+```
+
+Multiple segments via `items`:
+
+```tsx
+<IconText
+  items={[
+    { iconProps: { name: 'train', 'aria-hidden': 'true' }, text: 'Metro' },
+    {
+      iconProps: { name: 'arrow-right', 'aria-hidden': 'true' },
+      text: 'Airport',
+    },
+  ]}
+/>
+```
+
+Icons inside `IconText` sit next to their visible text — mark them decorative with
+`aria-hidden` (see SKILL.md's accessibility rules).

package/templates/skills/bestax-layout-scaffold/SKILL.md

@@ -36,8 +36,13 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi
 ## Approach
 
 - Compose pages from the shipped layout components — `Container`, `Section`, `Hero`, `Footer`,
-  `Level`, `Columns`/`Column`, `Navbar`, `Menu`, `Card`. There is **no `Tile` component** — build
-  grids with `Columns`/`Column`.
+  `Level`, `Columns`/`Column`, `Grid`/`Cell`, `Navbar`, `Menu`, `Card`. There is **no `Tile`
+  component**. For **uniform grids** (card grids, galleries — same-shaped items) prefer
+  `Grid`/`Cell`: CSS Grid gives equal-height cells for free (per row — each row's cells match
+  its tallest, same row-level behavior as the flex recipe). Use `Columns`/`Column` for
+  proportional or per-breakpoint column layouts — and when cards there must be equal height,
+  apply the flex recipe (`Column display="flex" flexDirection="column"` + `Card flexGrow="1"`;
+  `height: 100%` on the card doesn't help — the column's height is auto).
 - Rely on Bulma's responsive defaults: `Columns` sit side by side on tablet and up and stack on
   mobile. Add responsive `size*` props only to tune the breakpoints.
 - For a `fixed="top"` `Navbar`, add the `has-navbar-fixed-top` class to `<html>` so content is not
@@ -46,6 +51,13 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi
   `textAlign="centered"`, and `textColor`/`bgColor` instead of `style={{ marginTop, textAlign,
 color }}`. Set the app-wide icon library once with `<ConfigProvider iconLibrary="…">` at the root
   rather than `library` on every `<Icon>`.
+- **CTAs on a colored hero must stay legible in both schemes.** On a fixed-color surface
+  (`Hero color="primary"`, a dark banner), use **filled** buttons — `color="light"` or
+  `color="primary" isInverted` — never a thin `isOutlined` secondary: a light outline + light
+  label on a dark surface is low-contrast and gets worse under OS dark mode. And when the page's
+  design is single-mode (a fixed light or dark look), pin it at the root —
+  `<Theme isRoot colorMode="light">` — so a visitor's OS dark mode can't flip Bulma's text
+  colors out from under the fixed palette (details: the `bestax-theming` skill's contrast rules).
 
 ## References
 
@@ -67,7 +79,9 @@ color }}`. Set the app-wide icon library once with `<ConfigProvider iconLibrary=
 
 - [ ] Map the request to one archetype; do not ask layout questions.
 - [ ] Wrap page content in `Container` (+ `Section` for vertical rhythm).
-- [ ] Use `Columns`/`Column` for side-by-side layout; rely on the mobile stack default.
+- [ ] Use `Grid`/`Cell` for uniform grids (equal heights per row, free); `Columns`/`Column`
+      for proportional or per-breakpoint side-by-side layout — with the flex recipe when its
+      cards must match height.
 - [ ] For a fixed navbar, add `has-navbar-fixed-top` to `<html>`.
 - [ ] Do not use `Tile` — it is not shipped.
 - [ ] Style with helper props (`mt`/`p`, `textAlign`, `textColor`), not inline `style`.

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

@@ -1,6 +1,10 @@
 // Card grid / catalog page — a collection of similar items.
 // `<Columns isMultiline>` wraps cards onto new rows; the responsive column sizes
 // give 1 card per row on mobile, 2 on tablet, 3 on desktop.
+// Equal heights: each Column is a flex container and its Card grows to fill
+// 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,
@@ -78,8 +82,11 @@ export default function CatalogPage() {
               sizeMobile="full"
               sizeTablet="half"
               sizeDesktop="one-third"
+              display="flex"
+              flexDirection="column"
             >
               <Card
+                flexGrow="1"
                 image={product.image}
                 imageAlt={product.name}
                 header={product.name}

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

@@ -33,11 +33,16 @@ export default function LandingPage() {
             <SubTitle size="3">
               The all-in-one platform for modern teams.
             </SubTitle>
+            {/* Both CTAs are FILLED: on a fixed-color hero a thin outlined
+                button (light outline + light label) reads washed out, and
+                worse under OS dark mode. isInverted (no isOutlined) gives a
+                solid white button with primary text — high contrast in both
+                schemes. */}
             <Buttons isCentered mt="5">
               <Button color="light" size="large">
                 Get started
               </Button>
-              <Button color="primary" isInverted isOutlined size="large">
+              <Button color="primary" isInverted size="large">
                 Live demo
               </Button>
             </Buttons>

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

@@ -116,6 +116,12 @@ pricing page. The default for "build me a site/page".
 **Responsive:** `Section`s already stack vertically. The feature `Columns` collapse to one feature
 per row on mobile. Use `Hero size="large"` / `"fullheight"` for a taller hero.
 
+**Hero CTAs:** on a colored hero use **filled** buttons only — `color="light"` for the primary
+CTA and `color="primary" isInverted` (solid white, primary text) for a secondary. A thin
+`isOutlined` button on a fixed-color surface is low-contrast and degrades further under OS dark
+mode. Single-mode page designs should also pin the scheme at the root
+(`<Theme isRoot colorMode="light">`) — see the `bestax-theming` skill's contrast rules.
+
 ---
 
 ## 3. Centered single-column
@@ -159,8 +165,11 @@ search results, "a grid of cards".
           sizeMobile="full"
           sizeTablet="half"
           sizeDesktop="one-third"
+          display="flex"
+          flexDirection="column"
         >
           <Card
+            flexGrow="1"
             image={item.image}
             header={item.name}
             footer={<span className="card-footer-item">{item.price}</span>}
@@ -177,6 +186,14 @@ search results, "a grid of cards".
 **Responsive:** `isMultiline` wraps cards onto new rows; the `size*` props set the per-row count —
 1 on mobile, 2 on tablet, 3 on desktop here. Change the fractions to change the column count.
 
+**Equal heights:** the `display="flex" flexDirection="column"` on each `Column` plus
+`flexGrow="1"` on the `Card` stretches every card to its row's height — without it, cards end
+at their content and rows look ragged (`height: 100%` on the card doesn't help — it resolves
+against the column's auto height). Alternatively
+build the whole grid with `Grid`/`Cell` (`<Grid isFixed fixedColsMobile={1} fixedColsTablet={2}
+fixedColsDesktop={3} gap={4}>`) — CSS Grid keeps cells equal-height for free; see the
+`Grid / Cell` section in `layout-components.md`.
+
 ---
 
 ## Combining archetypes

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

@@ -12,6 +12,8 @@ import {
   Level,
   Columns,
   Column,
+  Grid,
+  Cell,
   Navbar,
   Menu,
   Card,
@@ -26,7 +28,9 @@ Every component also accepts the shared Bulma helper props (`m`/`p` spacing, `te
 > `textColor="grey"` / `bgColor="light"` not `style={{ color }}`. Spacing scale is `0`–`6` | `auto`
 > (`4` = 1rem). Reserve `style`/CSS vars only for values the design system doesn't tokenize.
 
-> **There is no `Tile` component.** Build grids and nested layouts with `Columns` / `Column`.
+> **There is no `Tile` component.** For uniform grids (cards, galleries) use `Grid` / `Cell` —
+> equal-height cells for free; for proportional or per-breakpoint layouts use
+> `Columns` / `Column`.
 
 ## Container
 
@@ -127,6 +131,76 @@ type BulmaColumnSize =
 > Columns **stack on mobile** by default and go side-by-side at the tablet breakpoint and up.
 > Use the per-breakpoint `size*` props to control how many cells share a row at each width.
 
+**Equal-height cards inside Columns** — columns are equal height, but a card inside one does
+**not** stretch to fill it (and `height: 100%` on the card doesn't help — it resolves against
+the column's auto height). Make the `Column` a flex container and let the card grow:
+
+```tsx
+<Columns isMultiline>
+  {items.map(item => (
+    <Column
+      key={item.id}
+      sizeTablet="half"
+      sizeDesktop="one-third"
+      display="flex"
+      flexDirection="column"
+    >
+      <Card flexGrow="1">{item.blurb}</Card>
+    </Column>
+  ))}
+</Columns>
+```
+
+`display`, `flexDirection`, and `flexGrow` are helper props every component accepts;
+`flexGrow` takes a string (`"1"`).
+
+## Grid / Cell
+
+Bulma's CSS Grid. **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).
+
+**Grid**
+
+| Prop                                                                                                                   | Type                                                         |
+| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `gap` / `columnGap` / `rowGap`                                                                                         | `0`–`8` (number or string, same scale as Columns' `gap`)     |
+| `minCol`                                                                                                               | `1`–`32` (smart grid: min column width step, `is-col-min-X`) |
+| `isFixed`                                                                                                              | `boolean` (fixed column count instead of auto-fill)          |
+| `fixedCols` (+ `fixedColsMobile` / `fixedColsTablet` / `fixedColsDesktop` / `fixedColsWidescreen` / `fixedColsFullhd`) | `0`–`12` or `'auto'` (fixed grid only)                       |
+
+**Cell**
+
+| Prop                                  | Type                                    |
+| ------------------------------------- | --------------------------------------- |
+| `colStart` / `colFromEnd` / `colSpan` | `number` (manual column placement/span) |
+| `rowStart` / `rowFromEnd` / `rowSpan` | `number` (manual row placement/span)    |
+
+By default the smart grid **auto-fills**: cells flow into as many columns as fit (tune the
+minimum width with `minCol`). `isFixed` + `fixedCols*` pins an exact column count per
+breakpoint instead.
+
+```tsx
+// Uniform card grid — equal heights for free, responsive column count for free.
+<Grid
+  isFixed
+  fixedColsMobile={1}
+  fixedColsTablet={2}
+  fixedColsDesktop={3}
+  gap={4}
+>
+  {items.map(item => (
+    <Cell key={item.id}>
+      <Card header={item.name}>{item.blurb}</Card>
+    </Cell>
+  ))}
+</Grid>
+```
+
+> To stretch each card to its cell's full (equal) height, the same `display="flex"
+flexDirection="column"` + `flexGrow="1"` pattern applies to `Cell` + `Card`.
+
 ## Navbar
 
 `<Navbar>` is the top bar. Subcomponents: `Navbar.Brand`, `Navbar.Item`, `Navbar.Link`,
@@ -150,6 +224,12 @@ flag to `Navbar.Menu active`. **A `fixed="top"` navbar requires `has-navbar-fixe
 document.documentElement.classList.add('has-navbar-fixed-top');
 ```
 
+**Routing:** in a routed app, don't use `href="#"` — render items as the router's link
+component. `Menu.Item as={Link} to="/x"` and `Navbar.Item as={Link} to="/x"` both compile
+without casts (their props allow extra keys). Drive `active` from `useLocation().pathname`.
+Full patterns (including Buttons that navigate and Next.js `href`): the docs guide at
+https://bestax.io/docs/guides/features/routing.
+
 ## Menu
 
 `<Menu>` is a vertical sidebar menu. Subcomponents: `Menu.Label`, `Menu.List`, `Menu.Item`.

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

@@ -35,6 +35,26 @@ For **dark mode**, pass `colorMode` to `Theme` (`'light' | 'dark' | 'system'`).
 `Theme`; `'system'` follows the OS `prefers-color-scheme`. Drive it from state on the app-root
 `Theme`: `<Theme isRoot colorMode={mode}>`.
 
+## Contrast rules (dark mode is on by default)
+
+When nothing sets a `data-theme` attribute (omitting `colorMode` preserves an existing one, but
+apps that never configured it have none), Bulma follows the visitor's OS: `--bulma-text`,
+`--bulma-scheme-main`, etc. flip on a dark-mode machine even if the design never intended a dark
+theme. Custom fixed tokens (`--my-canvas: #f6f4ec`) do **not** flip — producing near-white Bulma
+text on the author's fixed light background. Apply exactly one of these rules whenever custom
+color tokens or fixed-color surfaces exist:
+
+- **Single-mode design → pin the scheme.** `<Theme isRoot colorMode="light">` (or `"dark"`), so
+  an OS preference can never invert text out from under the fixed palette.
+- **Both modes → no exposed fixed tokens.** Derive custom tokens from scheme variables
+  (`--my-canvas: var(--bulma-scheme-main)`) — or flip them yourself under **both** dark-mode
+  paths: `[data-theme='dark']` **and** `@media (prefers-color-scheme: dark)` scoped to
+  `:root:not([data-theme])`, since `colorMode="system"` removes the attribute (snippets in
+  `references/css-variables.md`).
+- **Fixed-color surface → fixed-color content.** On a surface that never changes (a dark hero,
+  a brand banner), pin the content's colors too: solid/filled buttons and explicit text colors,
+  never scheme-derived defaults or thin outlines that depend on the flipping scheme.
+
 Reach for the helper props (`color` / `textColor` / `bgColor` / `colorShade`, `textSize`,
 `textWeight`, `fontFamily`) to apply themed colors and type to individual components.
 

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

@@ -147,6 +147,55 @@ Under dark mode Bulma flips the scheme/text/border/background lightness variable
 `Theme isRoot` or `:root` still apply on top, because they set the hue/saturation/lightness
 channels directly.
 
+### The single-mode contrast trap
+
+Because the OS preference applies whenever no `data-theme` attribute is set — the default state
+of every app that never configured `colorMode` — a light-only design silently breaks for any
+dark-mode visitor: Bulma's text goes near-white while author-defined fixed tokens stay light —
+white text on cream. The failure is invisible unless the author's own OS is in dark mode.
+
+**If the design is single-mode, pin the scheme** so text can't flip out from under the palette:
+
+```tsx
+<Theme isRoot colorMode="light">
+  <App />
+</Theme>
+```
+
+**If both modes are supported, never expose a fixed custom token to the flip** — derive it from
+scheme variables, or flip it yourself:
+
+```css
+/* Preferred: track the scheme automatically. */
+:root {
+  --my-canvas: var(--bulma-scheme-main);
+  --my-ink: var(--bulma-text);
+}
+/* Or, when custom values must be kept, provide the dark pair for BOTH
+   ways dark mode arrives — the explicit attribute (colorMode="dark")… */
+[data-theme='dark'] {
+  --my-canvas: #14251b;
+  --my-ink: #eef3e7;
+}
+
+/* …and the OS preference, which applies when no data-theme is set
+   (colorMode="system" removes the attribute): */
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) {
+    --my-canvas: #14251b;
+    --my-ink: #eef3e7;
+  }
+}
+```
+
+Deriving from scheme variables is preferred precisely because it covers both dark-mode paths
+with no extra selector.
+
+The same reasoning applies to **fixed-color surfaces** inside either kind of page (a dark hero,
+a brand banner): content sitting on a surface that never flips must use pinned colors — filled
+buttons and explicit text colors — not scheme-derived defaults (see the layout skill's hero CTA
+rule).
+
 ## `Theme` props (named)
 
 Color trios: `primaryH/primaryS/primaryL`, `linkH/linkS/linkL`, `infoH/S/L`, `successH/S/L`,