bestax-mcp 0.0.0

package/data/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/data/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/data/skills/bestax-layout-scaffold/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: bestax-layout-scaffold
+description: Scaffold a complete, responsive page layout with @allxsmith/bestax-bulma — app shells/dashboards, marketing/landing pages, centered auth/settings pages, and card-grid catalogs. Use when building a full page or overall app layout (not a single component).
+license: MIT
+---
+
+# Scaffolding a page layout with @allxsmith/bestax-bulma
+
+Turn a high-level request ("admin dashboard", "landing page", "login screen", "product catalog")
+into a complete responsive page built from bestax-bulma layout components.
+
+## Behavioral rule
+
+Select an archetype from the request and build it in one shot. Do **not** ask layout questions
+("how many columns?", "where should the nav go?", "what width?") — infer the structure from the
+request and proceed. The archetype determines the structure; fill it with the requested content.
+
+Ask **at most one** clarifying question, and only for a high-level fork the request genuinely does
+not imply: whether the page is **public-facing** (marketing) or an **internal tool** (authenticated
+app). When the request already signals this ("dashboard", "admin", "landing", "login", "pricing"),
+skip the question and default.
+
+## Select an archetype
+
+| Request signals                                                        | Archetype     |
+| ---------------------------------------------------------------------- | ------------- |
+| dashboard, admin, console, internal tool, authenticated app, "sidebar" | **App shell** |
+| landing, marketing, homepage, product/pricing page, public site        | **Landing**   |
+| login, sign up, auth, settings, checkout, a single focused form        | **Centered**  |
+| catalog, gallery, products, listing, "grid of cards", search results   | **Card grid** |
+
+Default when ambiguous: internal tool → App shell; public-facing → Landing; one focused task →
+Centered; a collection of items → Card grid. For mixed requests, pick the dominant intent (e.g.
+"admin dashboard with a product list" → App shell whose main column holds a Card grid).
+
+## Approach
+
+- Compose pages from the shipped layout components — `Container`, `Section`, `Hero`, `Footer`,
+  `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.
+- Interactive extras don't share a state API — never transfer one by analogy:
+  `Collapse trigger={node} open/defaultOpen onOpen/onClose`, `Tabs value={i}/onChange`
+  (each `Tabs.Tab`/`Tabs.Content.Item` requires `index={i}`, and `Tabs.Content` must be a
+  **child of `<Tabs>`** — the active-tab context lives on it; a sibling panel never
+  switches), `Dropdown active/onActiveChange`,
+  `Steps value={i}/onStepClick items={[{label, icon?}]}` (child form is `Steps.Step`, not
+  `Steps.Item`). `Reveal cascade` staggers only its **direct children** — to stagger a grid,
+  put `<Reveal delay={i * 80}>` inside each `Cell`, not around the container.
+- Link lists (footer nav, sidebars): a bare `UnorderedList` of `ListItem`s is already
+  marker-less and flush — Bulma's reset unstyles `ul` — so no prop or CSS is needed;
+  bullets appear only inside `Content`.
+- `Navbar.Burger`/`Navbar.Menu` are **controlled** — wire the same `active` state to both:
+  `active` on `Navbar.Menu` shows/hides the mobile menu, while `active` + `onClick` on
+  `Navbar.Burger` make the burger toggle it and animate. Left unwired, clicking the burger
+  does nothing (no error, silent failure). For a `fixed="top"` `Navbar`, add the
+  `has-navbar-fixed-top` class to `<html>` so content is not hidden behind it — the library
+  does not do this automatically, and an inline padding offset is not a substitute.
+- **Style with helper props — no inline `style`, no raw Bulma `className`s.** Before writing
+  `style={{ … }}` anywhere, translate each declaration with the mapping table below — the helper
+  props cover the common cases. Bare markup has wrapper elements that take all
+  helper props: `<Span textSize="7" textColor="grey">`, `Paragraph`, `Strong` — never a raw
+  `<span className="is-size-7 has-text-grey">`. Table cells: `Th`/`Td` take `textAlign="right"`,
+  `textWeight`, `textSize` directly (their `color` prop colors the cell; for muted cell text
+  wrap content in `Span textColor="grey"`). Set the app-wide icon library once with
+  `<ConfigProvider iconLibrary="…">` at the root rather than `library` on every `<Icon>`.
+- **Decorative CSS is budgeted: three compact rules, ≤13 lines per app — comments count:
+  at most one short inline note, never a file-header comment block — every value derived
+  from `--bulma-*`.** A marketing page gets at most one hero wash, one alternating section
+  band, and one featured-card ring, applied via `className` — no resets (Bulma ships one;
+  body/list margins are already zero) and no grid textures, masks, or multi-layer backdrops;
+  the components carry the design:
+
+  ```css
+  .hero-wash {
+    background-image: radial-gradient(
+      60rem 30rem at 20% -10%,
+      hsl(var(--bulma-primary-h) var(--bulma-primary-s) 50% / 0.2),
+      transparent 60%
+    );
+  }
+  .section-alt {
+    background: var(--bulma-scheme-main-bis); /* next band: -ter */
+  }
+  .featured-ring {
+    --bulma-shadow: 0 0 0 2px var(--bulma-primary);
+  }
+  ```
+
+  The ring works by overriding the **upstream token**, not the component's own var: `.card`
+  and `.box` re-declare `--bulma-card-shadow`/`--bulma-box-shadow` from `--bulma-shadow` on
+  their own selector, so setting _those_ from an ancestor never wins (same for
+  `--bulma-box-radius`; `--bulma-card-radius` is a literal with no ancestor route at all).
+  It has to be a CSS rule rather than `<Theme bulmaVars={{ '--bulma-shadow': … }}>`, because
+  `bulmaVars` is a closed typed record and `--bulma-shadow` is not one of its keys — that
+  exact call **does not compile**, and it was the single most repeated invention across this
+  library's cold-start evals. Either way the subtree stays theme- and dark-mode-aware.
+
+- **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).
+
+## Three components core Bulma will talk you out of
+
+Most of this library's additions get found on their own, because nothing in Bulma does the
+job. These three do not: each has a Bulma near-miss close enough to stop the search. Across
+44 cold-start builds, `Dialog` was used **zero** times and `LinkButton` in two thirds — and
+every miss shipped the "not this" column instead.
+
+| You need                                                    | Use                                                                                                                                                             | Not this                                                                                                             |
+| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| A brief confirmation after an action, self-dismissing       | `Toast` — mount `<ToastContainer position="top-right" />` once at the app root, then `toast.success('Saved')` (also `.danger`/`.warning`/`.info`) from anywhere | `Notification`/`Message` — static page elements you have to place, position and dismiss yourself                     |
+| A confirm or alert the user must answer before anything     | `Dialog` — mount `<DialogContainer />` at the root, then `if (await dialog.confirm({ title, message })) …`                                                      | `Modal` — an empty shell; the title, message, button row and confirm/cancel wiring are all yours to rebuild          |
+| A control that reads as text or a link but _does_ something | `LinkButton` (`variant="text" \| "ghost" \| "underline"`, optional `color`)                                                                                     | `<a href="#">`/`<div onClick>` (no keyboard or screen-reader support) or `Button color="text"` (still button-shaped) |
+
+Mounting a container without ever calling `toast.*`/`dialog.*` is not usage — the container is
+the mount point, the imperative call is the thing that shows something. Both also work as
+ordinary controlled components when you would rather hold the state yourself —
+`<Toast message … duration onClose>`, `<Dialog isOpen title message type onConfirm onCancel>` —
+but in an app with more than one call site the root container plus the imperative helper is
+less wiring, not more.
+
+## Inline style → helper prop mapping
+
+Look up the declaration you were about to inline. The spacing, typography, and flex helpers
+below are on every component; `textColor`/`bgColor` are on the content components you'll
+target (`Box`, `Block`, `Title`, `Content`, `Hero`, `Card`, …) — the ones with a semantic
+`color` variant (`Tag`, `Tabs`, `Panel`) take `color` instead; wrap content in a `Block` if
+you need a text color there. `Notification` is the mixed case: it takes `textColor`, but its
+background comes from the semantic `color` prop, not `bgColor`.
+
+| 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: …` in a flex layout                | no `gap` helper exists — space children with `m*` margins; `Grid` and `Columns` take a `gap` prop, so prefer those there                                       |
+
+No helper matches (e.g. `maxWidth`, a one-off gradient)? Add a named class to the project
+stylesheet (`src/App.css` in a scaffolded app) and pass it via `className` — still never
+inline `style`.
+
+## References
+
+- `references/layout-components.md` — the layout component inventory: real prop names, types, and
+  accepted values, plus subcomponent nesting.
+- `references/archetypes.md` — the four archetypes: selection criteria, JSX skeleton, and responsive
+  behavior.
+
+## Examples
+
+- `examples/app-shell.tsx` — fixed `Navbar` + sidebar `Menu` + content (dashboard).
+- `examples/landing.tsx` — fixed `Navbar` (controlled burger) + `Hero` + `Section`s + `Footer`.
+- `examples/centered.tsx` — centered single column (auth/settings).
+- `examples/card-grid.tsx` — multiline `Columns` of `Card`s (catalog).
+- `examples/content-page.tsx` — hero + feature cards + CTA styled with helper props (no inline
+  `style`), wrapped in `ConfigProvider`.
+
+## Checklist
+
+- [ ] Map the request to one archetype; do not ask layout questions.
+- [ ] Wrap page content in `Container` (+ `Section` for vertical rhythm).
+- [ ] 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.
+- [ ] Wire `active` state to **both** `Navbar.Burger` and `Navbar.Menu` (they are controlled).
+- [ ] For a fixed navbar, add `has-navbar-fixed-top` to `<html>`.
+- [ ] Do not use `Tile` — it is not shipped.
+- [ ] Action feedback goes through `Toast`, a confirmation through `Dialog`, a text-styled
+      action through `LinkButton` — not `Notification`, `Modal` or a bare `<a>`.
+- [ ] Style with helper props, not inline `style` — translate via the mapping table; values
+      with no helper get a named class in the stylesheet, never `style={{}}`. No raw Bulma
+      `className`s either (`Span`/`Paragraph` wrap bare text; `Th`/`Td` take `textAlign`/`textWeight`).
+- [ ] Decorative CSS ≤13 lines total incl. comments — no file-header comment (hero wash +
+      section band + featured-card ring), `--bulma-*`-derived; no resets — Bulma ships one.
+      The ring sets `--bulma-shadow` in a CSS rule; `Theme bulmaVars` has no such key.
+- [ ] Set the icon library once via `<ConfigProvider iconLibrary="…">` at the root.
+- [ ] Site built? ~800 KB raw / ~82 KB gzip CSS is the expected default-flavor size — to shrink
+      it, run the `bestax-optimize` skill (measure first).

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

@@ -0,0 +1,86 @@
+// App shell with sidebar — fixed top Navbar + a narrow Menu column beside the
+// main content. The admin/dashboard default.
+//
+// A fixed-top navbar needs the `has-navbar-fixed-top` class on <html> so the page
+// is padded below it — Bulma requires this and the library does NOT add it for
+// you. In a real app set it statically in index.html; the useEffect below is the
+// fallback for a conditionally-mounted navbar (and keeps this file self-contained).
+// The columns sit side by side on tablet and up, and stack (menu above
+// content) on mobile.
+//
+// `ConfigProvider` wraps the shell once at the root to set the app-wide icon
+// library (so <Icon> needs no `library` prop) and, optionally, a class prefix.
+import React, { useEffect, useState } from 'react';
+import {
+  ConfigProvider,
+  Navbar,
+  Menu,
+  Container,
+  Columns,
+  Column,
+  Section,
+  Title,
+  Box,
+} from '@allxsmith/bestax-bulma';
+
+export default function AdminShell() {
+  const [menuOpen, setMenuOpen] = useState(false);
+
+  useEffect(() => {
+    document.documentElement.classList.add('has-navbar-fixed-top');
+    return () => {
+      document.documentElement.classList.remove('has-navbar-fixed-top');
+    };
+  }, []);
+
+  return (
+    <ConfigProvider iconLibrary="fa">
+      <Navbar fixed="top" color="dark">
+        <Navbar.Brand>
+          <Navbar.Item href="#">Acme Admin</Navbar.Item>
+          <Navbar.Burger
+            active={menuOpen}
+            onClick={() => setMenuOpen(open => !open)}
+            aria-label="menu"
+            aria-expanded={menuOpen}
+          />
+        </Navbar.Brand>
+        <Navbar.Menu active={menuOpen}>
+          <Navbar.End>
+            <Navbar.Item href="#">Docs</Navbar.Item>
+            <Navbar.Item href="#">Account</Navbar.Item>
+          </Navbar.End>
+        </Navbar.Menu>
+      </Navbar>
+
+      <Container fluid>
+        <Columns>
+          <Column size={3} sizeWidescreen={2}>
+            <Menu>
+              <Menu.Label>General</Menu.Label>
+              <Menu.List>
+                <Menu.Item active href="#">
+                  Dashboard
+                </Menu.Item>
+                <Menu.Item href="#">Customers</Menu.Item>
+                <Menu.Item href="#">Orders</Menu.Item>
+              </Menu.List>
+              <Menu.Label>Admin</Menu.Label>
+              <Menu.List>
+                <Menu.Item href="#">Team</Menu.Item>
+                <Menu.Item href="#">Settings</Menu.Item>
+              </Menu.List>
+            </Menu>
+          </Column>
+
+          <Column>
+            <Section>
+              <Title size="3">Dashboard</Title>
+              <Box>Main content area — drop dashboard widgets here.</Box>
+            </Section>
+          </Column>
+        </Columns>
+      </Container>
+    </ConfigProvider>
+  );
+}

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

@@ -0,0 +1,106 @@
+// 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,
+  Container,
+  Title,
+  Columns,
+  Column,
+  Card,
+} from '@allxsmith/bestax-bulma';
+
+interface Product {
+  id: number;
+  name: string;
+  price: string;
+  image: string;
+  blurb: string;
+}
+
+const PRODUCTS: Product[] = [
+  {
+    id: 1,
+    name: 'Aurora Lamp',
+    price: '$48',
+    image: 'https://picsum.photos/seed/1/600/400',
+    blurb: 'Warm ambient light.',
+  },
+  {
+    id: 2,
+    name: 'Drift Chair',
+    price: '$220',
+    image: 'https://picsum.photos/seed/2/600/400',
+    blurb: 'Ergonomic and airy.',
+  },
+  {
+    id: 3,
+    name: 'Stone Mug',
+    price: '$18',
+    image: 'https://picsum.photos/seed/3/600/400',
+    blurb: 'Hand-thrown ceramic.',
+  },
+  {
+    id: 4,
+    name: 'Field Notebook',
+    price: '$12',
+    image: 'https://picsum.photos/seed/4/600/400',
+    blurb: 'Pocket-sized, lined.',
+  },
+  {
+    id: 5,
+    name: 'Trail Bottle',
+    price: '$26',
+    image: 'https://picsum.photos/seed/5/600/400',
+    blurb: 'Insulated steel.',
+  },
+  {
+    id: 6,
+    name: 'Linen Throw',
+    price: '$64',
+    image: 'https://picsum.photos/seed/6/600/400',
+    blurb: 'Soft, breathable.',
+  },
+];
+
+export default function CatalogPage() {
+  return (
+    <Section>
+      <Container>
+        <Title size="3" mb="5">
+          Catalog
+        </Title>
+        <Columns isMultiline>
+          {PRODUCTS.map(product => (
+            <Column
+              key={product.id}
+              sizeMobile="full"
+              sizeTablet="half"
+              sizeDesktop="one-third"
+              display="flex"
+              flexDirection="column"
+            >
+              <Card
+                flexGrow="1"
+                image={product.image}
+                imageAlt={product.name}
+                header={product.name}
+                // Card wraps each footer item in .card-footer-item itself —
+                // no raw span/className needed (and a literal class would
+                // break under ConfigProvider classPrefix).
+                footer={product.price}
+              >
+                <p>{product.blurb}</p>
+              </Card>
+            </Column>
+          ))}
+        </Columns>
+      </Container>
+    </Section>
+  );
+}

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

@@ -0,0 +1,56 @@
+// Centered single-column page — auth, settings, focused forms.
+// A narrow column is centered with `<Columns isCentered>`; on mobile the column
+// becomes full width automatically.
+import React from 'react';
+import {
+  Section,
+  Container,
+  Columns,
+  Column,
+  Box,
+  Title,
+  SubTitle,
+  Input,
+  Button,
+} from '@allxsmith/bestax-bulma';
+
+export default function LoginPage() {
+  return (
+    <Section>
+      <Container>
+        <Columns isCentered>
+          <Column
+            size="half"
+            sizeTablet="two-thirds"
+            sizeDesktop="half"
+            sizeWidescreen="one-third"
+          >
+            <Box>
+              <Title size="4" textAlign="centered">
+                Sign in
+              </Title>
+              <SubTitle size="6" textAlign="centered" textColor="grey">
+                Welcome back
+              </SubTitle>
+              <Input
+                label="Email"
+                type="email"
+                iconLeftName="envelope"
+                placeholder="you@example.com"
+              />
+              <Input
+                label="Password"
+                type="password"
+                iconLeftName="lock"
+                placeholder="••••••••"
+              />
+              <Button color="primary" isFullWidth mt="4">
+                Sign in
+              </Button>
+            </Box>
+          </Column>
+        </Columns>
+      </Container>
+    </Section>
+  );
+}