bestax-layout-scaffold

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

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 onOpenChange (onOpenChange(open) reports every trigger; onOpen/onClose fire only when the Collapse holds its own state), an accordion is Collapses value/defaultValue/onChange around plain Collapse children indexed from 0 by position (number | null, or number[] with multiple; hide an item with visibility="hidden", never {cond && …}, or the open state shifts to its neighbour) rather than hand-rolled open-index state, 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. The arrow keys, Home/End, Enter/Space, the single tab stop and the aria-controls/aria-labelledby links come built in, so add no onKeyDown or ARIA of your own; onChange fires when a tab is activated, never on arrow-key focus), Dropdown active/onActiveChange, ToggleButton pressed/defaultPressed onPressedChange for a button that stays on or off (not Button isActive, which sets no aria-pressed; the label stays the same in both states; a set goes in Buttons hasAddons role="group" with an aria-label, where it's also Buttons.ToggleButton, and a row where only one can be on is SegmentedControl), SegmentedControl aria-label="…" value/defaultValue onChange for a row of buttons where only one can be on, such as a list or grid view (one SegmentedControl.Segment value="…" per option; a radio group with the single tab stop and the arrow keys built in, so add no onKeyDown of your own; an icon-only segment needs its own aria-label; the arrows check as they move, so onChange(value) fires on each, and it can't be cleared; it carries no form value, so a choice a form submits is Radios), Popover trigger={<Button>…</Button>} open/defaultOpen onOpenChange (trigger is one element, not a node: Popover clones it to add the click and ARIA, so never wrap it in a clickable of your own; build the panel from Popover.Header/Body/Footer/Close, and a panel without a Popover.Header needs ariaLabel), HoverCard trigger={<Link href="…">…</Link>} for a preview on hover or keyboard focus (trigger is one link or button, cloned the same way; the card's content goes straight in as children with no sub-components; a trigger inside a Paragraph needs appendToBody; hover and focus only unless openOnTap is set, which suits only a trigger with no tap action of its own, such as a Button with no onClick; on touch a link trigger just follows the link, so what the card shows must be on that page too, and a form is a Popover), ContextMenu aria-label="…" trigger={<Table.Tr>…</Table.Tr>} for actions on a right-click or a long press (trigger is one element, a row or a card, cloned rather than wrapped; the items are ContextMenu.Item/ContextMenu.Divider, which are Dropdown's; no open prop, onOpenChange reports it; always put the same items in a visible Dropdown on the row too, since a context menu is only a shortcut), 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.
• An empty list, table or search with no results is EmptyState, not a hand-built Box of Icon, Title and Buttons isCentered: <EmptyState icon="folder-open" title="No projects yet" titleAs="h3" description="…"> with its one <Button> as a child (two or more go in EmptyState.Actions). Its title is always a heading, so set titleAs to the level under the list's own heading. It has no live region: after a search or a filter, keep a Paragraph with role="status", aria-atomic="true" and visibility="sr-only" beside the search field the whole time, saying the count, and have "Clear search" put focus back in the field. While data loads show a Skeleton or a Loader, and a failed load is a Message or a Notification, never an EmptyState. The archetypes reference has the full pattern under Card grid.
• A table people sort, search, page through or pick rows from is DataTable, not a Table with sort state, aria-sort, checkboxes and a Pagination wired by hand: <DataTable caption="Users" columns={[{ id: 'name', header: 'Name', sortable: true, isRowHeader: true }, …]} data={rows} selectionMode="multiple" pageSize={10} hasSearch />. A column is { id, header }, reading row[id], plus accessor (the raw value, which sorts), format (its text, which the cell shows and the search matches) and cell (rich content). It needs a caption, aria-label or aria-labelledby, and it shows its own EmptyState and says the match count itself. toolbar={table => …} holds buttons that act on table.state.selected or call table.setFilter; useDataTable({ columns, data, … }) returns the same table for <DataTable table={table} /> or for markup of your own through its get…Props getters; manual with rowCount hands sorting, filtering and paging to a server. table.toCSV() writes what's shown as CSV, escaping formulas, for a download button; there's no Excel export. A table with nothing to sort, search or pick stays Table.
• An order's history, a ticket's activity, a changelog or an activity feed is Timeline, not a hand-built list with a border down the side: <Timeline titleAs="h3"> with a <Timeline.Item title="Shipped" time="14 October 2026" dateTime="2026-10-14"> per event, any detail as its children, and the whole date in time. titleAs is the level under the section's heading, or "p" in a busy feed. For something that moves along on its own, like a parcel or a deployment, active={i} marks progress and pending="Out for delivery" ends it on what's under way, oldest first. A journey the user moves through, like a wizard or a checkout, stays Steps.
• Facts about one thing, each a label and its value (an order summary, a profile, a file's details), are DescriptionList, not Columns of label and value or a two-column Table: <DescriptionList aria-labelledby="order-heading"> under a Title id="order-heading", with a <DescriptionList.Item label="Order" value="#1234" /> per fact. It stacks on a phone and puts the labels beside their values from tablet up, so add no breakpoint code; orientation pins it. Several values, or a label with an info tip, go in as DescriptionList.Label and DescriptionList.Value children. Several records with the same fields stay a Table, and so do facts a screen reader must announce with their labels, as a Table with scope="row" headers.
• A number shown to the reader (a price, a total, a count, a percentage, a dashboard figure) is NumberFormatter, not toLocaleString() or an Intl.NumberFormat built by hand: <NumberFormatter value={8456.4} format={{ style: 'currency', currency: 'USD' }} />, with any Intl.NumberFormat options in format (style: 'percent' takes a fraction, 0.125 for 12.5%). It writes in its own locale, else the LocaleProvider's, else the runtime's, so a server-rendered app sets a locale on a LocaleProvider at the root. Its text is the number alone, so words go around it: Total: <NumberFormatter … />. Text that can't hold an element, an aria-label or a placeholder, gets the same from const format = useNumberFormat(); and format(1500, { style: 'currency', currency: 'EUR' }).
• A file browser, a checkbox tree (permissions, filters) or an outline you browse is TreeView, with <TreeView.Item value="…" label="…" icon="folder"> items nested inside each other: <TreeView aria-label="Files" selectionMode="single"> with selected/onSelectedChange picks one, and selectionMode="checkbox" with checked/onCheckedChange draws boxes with mixed parents, where a parent's value checks its whole branch. For categories, where checking a parent means only the parent, selectionMode="checkbox-independent" draws a box per item that checks that item alone, with no mixed parents. Map the data with a recursive function, and render an item's children whether it's open or not. A folder that loads when it opens takes hasChildren, isLoading while its children are on their way, and loadError="Couldn't load src" with onRetry when the load fails, setting isLoading again while the retry runs: the tree draws the Loading… and Retry rows and announces them, so don't hand-write a placeholder item. Its items aren't links, so the app's sidebar and any list of pages stay on Menu with Menu.Item href.
• A sidebar whose groups of links open and close is Menu.Section, one per group, directly in Menu (never inside a Menu.Item or Menu.List): <Menu.Section label="Components" defaultOpen> around that group's Menu.List, with defaultOpen on the group holding the current page (or open/onOpenChange to hold the state). Its heading is a real button with aria-expanded, and its links stay links, each a tab stop. Not TreeView, and not a Collapse inside a hand-written <li>.
• An app's frame, a header across the top with a navigation column down the side, is AppFrame, not a fixed Navbar over Columns: <AppFrame> with AppFrame.Header (a Navbar with <AppFrame.Burger /> in its Navbar.Brand), AppFrame.Nav (the Menu) and AppFrame.Main (the page), plus AppFrame.Aside and AppFrame.Footer when there are any. The header and the column stick on their own, so no fixed and no has-navbar-fixed-top; below desktop the column is a drawer the burger opens, and from desktop up the burger collapses it. It renders the page's <main>, so it goes at the top of the app, never inside a <main>.
• Panes the user resizes are Splitter (a file tree beside an editor, a list beside its detail, a query above its results), not hand-written drag code or fixed Columns: <Splitter height={480}> with a <Splitter.Pane label="Files" defaultSize={25} minSize="12rem"> per pane. The handles go in on their own, each named by its pane's label, so give every pane one. Sizes are percentages, limits also take px or rem, orientation="vertical" stacks them (and needs a height), and collapsible with collapsed/onCollapsedChange lets a button hide a pane. Put scrolling content in a ScrollArea inside the pane.
• Content taller or wider than its space is ScrollArea (release notes in a Card, a sidebar longer than the screen, a feed that grows then scrolls, a wide table on a phone), not a Box with overflowY="auto" and a height in a style: <ScrollArea height={240} aria-label="…">, or maxHeight="20rem" to grow with its content first. It needs aria-label or aria-labelledby, since while it overflows it's a region a keyboard user tabs to. The helper props and className go on its frame and the ref on the element that scrolls. hasFade fades the edges that have more, orientation="horizontal" suits a wide table, and onEdgeReach={edge => …} loads more at an edge.
• Something that stays in a corner of the screen (a floating button, a chat or help launcher, a feedback tab, a consent notice) is Affix, not pos="fixed" with offsets in a style: <Affix position="bottom-left"><Button color="primary">Feedback</Button></Affix>. position is one of the four corners, 'bottom-right' by default, and stays physical in right-to-left text. The spacing helpers nudge one further in (mb="6" lifts it over a bottom bar), and portal moves it out of an ancestor with a transform. Two in one corner overlap, so put what shares a corner in one Affix. Tab reaches it where it is in the markup, whatever corner it shows in, so write it after the main content. For an element pinned once the page scrolls past it, use pos="sticky" with a top instead.
• A command palette (⌘K or Ctrl+K) is Command.Dialog, not a Modal with an Input and a hand-written keydown listener: <Command.Dialog shortcut="mod+k" placeholder="…" actions={[…]} />, each action { id, label, onSelect } with group, keywords, description, icon and hint (a Kbd.Group) as it needs them. Typing filters the actions by label, keywords and description, Enter runs the top match, and running one closes the dialog. shortcut is off unless given, and it does nothing while the user types in a field. A button that opens it too uses open and onOpenChange, with aria-keyshortcuts on the button. The same list inline, in a page or a Popover, is Command. For server results, build it from parts: Command.Input, then Command.List of Command.Items, or Command.Empty, filtered from onQueryChange.
• Link lists (footer nav, sidebars): a bare UnorderedList of ListItems 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 classNames. 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>. An app in another language, or a right-to-left one, also gets lang and dir on <html> and a <LocaleProvider locale="…"> at the root, so overlays and date pickers follow it.
• Alternating section bands are a prop, not CSS: bgColor="scheme-main-bis" on every other Section (next band scheme-main-ter). The scheme values render as a dark-mode-safe inline background-color: var(--bulma-scheme-*) — zero custom CSS — and still never bgColor="light"/"white": those are fixed colors that stay light when dark mode flips the text.
• Decorative CSS is budgeted: two compact rules, ≤10 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 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: