Claude Skill

bestax-custom-component

Build a custom React component in the bestax/Bulma style. In an app using @allxsmith/bestax-bulma — compose existing components, helper props, public hooks (useBulmaClasses, usePrefixedClassNames), and --bulma-* CSS variables. In the bestax monorepo — the full component pipeline

LLM Mart · 0 points · 1 views 62 listing impressions 0 install-command copies
Download allxsmith-bestax-skills_bestax-custom-component-8fda6de.zip · 34 KB

Install

skills CLI npx skills add https://github.com/allxsmith/bestax/tree/main/skills/bestax-custom-component
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allxsmith-bestax@llmmart
Git git clone https://github.com/allxsmith/bestax.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole allxsmith/bestax collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Building a custom component the bestax way

This skill teaches how to build a component that isn't in the library — composed from bestax pieces in an app, or as a full library "extra" inside the bestax monorepo.

Which context are you in?

  • The bestax monorepo (the repo contains bulma-ui/src/) → follow references/library-contributor.md instead of this file: five-file layout, SCSS partial, stories, Vitest tests, docs page, wiring.
  • An app depending on @allxsmith/bestax-bulma (e.g. scaffolded by npm create bestax) → continue here. Everything below assumes public package imports and a plain Vite app.

For form components (Field/Control/Input/etc.) use the bestax-form skill instead.

Check for an existing component first

Before building anything, search the library for a component that already does this — or a close synonym — and tell the user what you found. Many requests are covered by an existing element, or are best built by composing existing ones. Building a near-duplicate (a "label" when Tag exists, a "banner" when Notification exists) fragments the API and is usually the wrong call.

Where to look:

  • references/component-catalog.md — start here. Every documented component with a one-line purpose, grouped by category. Scan it for the name and its synonyms before anything else.
  • https://bestax.io/docs/api — one doc page per shipped component (full props).

Then decide, and surface the decision to the user:

  • Exact / synonym match exists → recommend using it. Don't build a duplicate. (E.g. a small colored label/badge/chip → Tag / Tags already exist.)
  • Partial overlap → prefer composing the existing pieces inside your new component rather than re-implementing them. (E.g. a "profile card" → there's no ProfileCard, but Card, Image, Title, SubTitle, and Content exist; build ProfileCard to compose them.)
  • Genuine gap → build the new component using the pattern below.

State plainly which case applies before writing code, e.g. "Tag already covers a colored label — use that instead" or "No ProfileCard exists; I'll build one composing the existing Card/Image/Title elements."

Composition first

Build from existing components before writing any CSS: Box, Card, Title, SubTitle, Icon, Block, Content, Tag, plus the shared Bulma helper props (spacing, color, typography, flexbox). Some compound sub-parts are the exception — Modal.Card, Tabs.Tab, Message.Body take no Bulma helper props, just className + HTML attributes plus their own few (Tabs.Tab requires index={i} and has built-in disabled and icon/iconLibrary/iconVariant/iconSize/iconFeatures — don't nest an <Icon> there) — so put helper props on the parent or on an element inside them, never invent them there. (Card.* sub-parts do take helper props, like Table.*/Menu.*/Hero.*.) Most "custom components" are a composition function — zero new styles. See examples/stat-card.tsx for a complete worked example.

Rendering something only the browser knows (the reader's time zone, a localStorage value)? Wrap it in the library's ClientOnly rather than checking typeof window: it renders a fallback until the page has hydrated, so the server and client markup match. references/api.md has the details.

A button that shows only an icon (Delete in a table row, Settings in a navbar) is IconButton: <IconButton icon="trash" aria-label="Delete" />, rather than a Button holding an Icon. The glyph goes in icon or as the one child (<Icon name="trash" />, or an SVG), not both. Its types require aria-label, or aria-labelledby in its place, so name the action, not the picture. It takes every Button prop, is type="button" unless you pass submit or reset, and isRounded makes it a circle. Several go in Buttons, where it's also Buttons.IconButton. For a description on hover, wrap it in Tooltip, which describes it and doesn't name it.

A button that copies text (a share link, an API key, an install command) is CopyButton: <CopyButton value={url} />, rather than a Button calling navigator.clipboard yourself. It falls back to the copy command where the Clipboard API is missing, reports a failure rather than showing "Copied", reads "Copied" for duration ms (2000, and 0 keeps it, as on Toast), and announces each result in a status region it portals, so it can sit last in a Control or Buttons, where it's also Buttons.CopyButton. showLabel={false} makes it an icon-only IconButton named by labels.copy. Its callbacks are onCopiedChange and onCopyError (not onCopy/onError, which are DOM events), and an onClick that calls preventDefault() stops the copy. For a trigger of your own, use useClipboard.

A button that turns something on or off and stays that way (Bold, Mute, Show archived) is ToggleButton: use it rather than Button isActive, which only draws a shade and sets no aria-pressed. It's always type="button", holds its own state (defaultPressed) or takes pressed with onPressedChange, and fills with color (default link) only while pressed. Its label stays the same in both states, and an icon-only one needs an aria-label. A set goes in Buttons hasAddons role="group" aria-label="…", where it's also Buttons.ToggleButton. A row where only one can be on is a radio group, so it's SegmentedControl (below), never toggles that switch each other off. A setting saved with a form is a Switch or a Checkbox.

A row of buttons where only one can be on (text alignment, a list or grid view, monthly or yearly billing) is SegmentedControl: use it rather than Buttons hasAddons with isActive or a fill you move yourself. Give it an aria-label, put one SegmentedControl.Segment value="…" inside per option, and hold the choice with defaultValue, or value with onChange(value). A screen reader hears a radio group, and the single tab stop, the arrow keys, Home and End come built in, so add no onKeyDown or role of your own. An icon-only segment needs its own aria-label, as an icon-only ToggleButton does. The arrow keys check the segment they land on, so onChange fires on each, and pressing the checked segment keeps it checked. It carries no form value: a choice the form submits is Radios.

A panel opened from a button (a filter form, share options, an inline edit) is Popover: use it rather than building one. It anchors the panel, moves focus in and back, and closes on Escape and outside presses.

A preview that shows up on hover (a profile card on a username, a summary on a link) is HoverCard: use it rather than wiring pointer events to a Popover. It opens on hover and keyboard focus after a delay, lets the pointer move onto the card, closes on Escape, and ignores touch unless openOnTap is on, which suits only a trigger with no tap action of its own (a Button with no onClick, never a link). Its trigger has to be a link or a button, and a trigger in running text takes appendToBody. A form never goes in one; that's Popover.

A menu of actions that opens on a right-click (Rename and Delete on a table row, Archive on a card) is ContextMenu: use it rather than an onContextMenu handler that positions a Dropdown. It opens at the point, also on Shift+F10, the context menu key and a long press, and its items are ContextMenu.Item and ContextMenu.Divider, the same components as Dropdown.Item and Dropdown.Divider. Its trigger is cloned, not wrapped, so a Table.Tr works, and the menu needs aria-label. Put the same items in a visible Dropdown as well: nothing tells a screen reader user a context menu is there, and on macOS only VoiceOver opens it from the keyboard.

A command palette, a search over things to do that opens on ⌘K or Ctrl+K, is Command.Dialog: <Command.Dialog shortcut="mod+k" actions={[{ id, label, onSelect }]} />, or built from parts for a server search. Don't hand-build one from Portal, useFocusTrap and a keydown listener. Inline, without the modal, it's Command.

Building something else that floats? Render it through the library's Portal rather than createPortal: it renders nothing on the server and during hydration, so the server and client markup match. references/api.md has the details.

Building some other overlay that holds focus until it is dismissed? Use the library's useFocusTrap rather than a hand-rolled Tab handler: it finds the tab stops the browser visits and hands focus back on close. references/api.md has the signature and a worked panel.

The component spine

Same shape the library itself uses, with all imports from the package. Every reusable component gets it — including pure compositions with zero CSS (a heading block, a labeled wrapper): extend BulmaClassesProps, run your props through useBulmaClasses, merge its bulmaHelperClasses into className, and spread the rest it returns — spreading the raw props instead leaks helper props onto the DOM and emits none of their classes. The usePrefixedClassNames root class is needed only when component-scoped CSS (or a variant class) targets it — a zero-CSS composition may omit that call. File at src/components/MyComponent.tsx:

import type React from 'react';
import {
  classNames,
  usePrefixedClassNames,
  useBulmaClasses,
  type BulmaClassesProps,
} from '@allxsmith/bestax-bulma';

export interface MyComponentProps
  extends
    Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>,
    Omit<BulmaClassesProps, 'color'> {
  color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
}

export function MyComponent({
  color,
  className,
  children,
  ...props
}: MyComponentProps) {
  const { bulmaHelperClasses, rest } = useBulmaClasses(props);
  const mainClasses = usePrefixedClassNames('mycomponent', {
    [`is-${color}`]: !!color,
  });
  return (
    <div
      className={classNames(mainClasses, bulmaHelperClasses, className)}
      {...rest}
    >
      {children}
    </div>
  );
}

This gives your component the full Bulma helper-prop surface (m, p, textAlign, …) for free. references/api.md documents the helpers.

Styling ladder — use the lowest rung that works

Rung 1 — helper props only (default). House rules: never style={{}}. Lay children out with Stack (a column), Group (a row that wraps), Center or Flex, which are flex containers already and zero the margins Bulma gives their children, so gap is the only space; alignItems, justifyContent and the rest go straight on them. Don't reach for Box as a plain flex container: it's a padded, shadowed surface. Before writing style={{ … }} anywhere, translate each declaration:

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). On Title/SubTitle, as sets the level and size picks it too, so an <h3> at size 4 is as="h3" textSize="4"
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 you'll compose with (Box, Block, Title, Content, 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.

A value with no helper equivalent (maxWidth: 720, a one-off gradient) moves you to rung 2 — a named class in a stylesheet — never to inline style.

Rung 2 — a plain CSS file, scoped under the component's class, consuming --bulma-* variables — never literal colors, so Theme and dark mode keep working:

/* src/components/MyComponent.css — import from the .tsx file */
.mycomponent {
  /* component-scoped custom props, initialized from Bulma tokens:
     any ancestor (or Theme) can re-theme by overriding them */
  --mycomponent-radius: var(--bulma-radius);
  --mycomponent-accent: var(--bulma-primary);
  border-radius: var(--mycomponent-radius);
  border: 1px solid var(--bulma-border);
  background: var(--bulma-scheme-main);
  color: var(--bulma-text);
}
.mycomponent .mycomponent-value {
  color: var(--mycomponent-accent);
}

Caveat: with the prefixed CSS flavor / ConfigProvider classPrefix, usePrefixedClassNames prefixes your classes too — your CSS selectors must match (or build them with plain classNames instead).

Rung 3 — real Sass (optional). npm i -D sass — nothing else; Vite compiles imported .scss zero-config, and bulma is resolvable because it's a runtime dependency of bestax-bulma. Then the full register-vars/getVar pattern from references/library-contributor.md works in-app. Prefixed flavor: @use 'bulma/sass/utilities/initial-variables' with ($class-prefix: 'bestax-').

Verify in the browser

Types don't see layout. Run npm run dev, render the component, and actually look at it: vertical centering of inline text (use display="flex" alignItems="center", not line-height hacks), balanced padding, nothing clipping, every color/size variant, and dark mode legibility. Fix what you see, then re-check. No browser available (headless)? Fall back to npm run build plus a Node renderToString smoke render, grep the emitted HTML for the expected classes, and flag the visual pass as not done.

Tests and stories in an app

The scaffolded app has no test runner and no Storybook — do not install or scaffold them unasked. If the app already has vitest/jest + Testing Library, write the four test shapes: render, prop→class mapping, helper-prop passthrough (m="3" → m-3), and the ConfigProvider classPrefix case if the app uses a prefix.

Checklist

  • Inventory checked (catalog + bestax.io/docs/api) and the decision surfaced to the user.
  • All imports from @allxsmith/bestax-bulma (no deep/internal paths).
  • Composition first — existing components + helper props before any CSS; every reusable component gets the spine.
  • No inline style={{}} anywhere — translate via the rung-1 mapping table; values with no helper equivalent get a named class (rung 2).
  • Lowest sufficient ladder rung (helper props → scoped CSS vars → Sass).
  • All colors/radii derived from --bulma-* variables — no literals.
  • Renders correctly via npm run dev, including dark mode.
Files (bestax)
  • examples
    • stat-card.tsx 3.6 KB · in bundle
  • references
    • api.md 16.5 KB
      Loading…
    • component-catalog.md 26.3 KB
      Loading…
    • library-contributor.md 23.3 KB
      Loading…
    • patterns.md 4.5 KB
      Loading…
  • SKILL.md 17.1 KB
    ---
    name: bestax-custom-component
    description: Build a custom React component in the bestax/Bulma style. In an app using @allxsmith/bestax-bulma — compose existing components, helper props, public hooks (useBulmaClasses, usePrefixedClassNames), and --bulma-* CSS variables. In the bestax monorepo — the full component pipeline (SCSS partial, stories, tests, docs, wiring). Use when creating a component beyond stock Bulma or extending one.
    license: MIT
    ---
    
    # Building a custom component the bestax way
    
    This skill teaches how to build a component that isn't in the library — composed from bestax
    pieces in an app, or as a full library "extra" inside the bestax monorepo.
    
    ## Which context are you in?
    
    - **The bestax monorepo** (the repo contains `bulma-ui/src/`) → follow
      `references/library-contributor.md` instead of this file: five-file layout, SCSS partial,
      stories, Vitest tests, docs page, wiring.
    - **An app depending on `@allxsmith/bestax-bulma`** (e.g. scaffolded by `npm create bestax`) →
      continue here. Everything below assumes public package imports and a plain Vite app.
    
    For **form** components (Field/Control/Input/etc.) use the `bestax-form` skill instead.
    
    ## Check for an existing component first
    
    Before building anything, **search the library for a component that already does this — or a
    close synonym** — and tell the user what you found. Many requests are covered by an existing
    element, or are best built by composing existing ones. Building a near-duplicate (a "label" when
    `Tag` exists, a "banner" when `Notification` exists) fragments the API and is usually the wrong
    call.
    
    Where to look:
    
    - `references/component-catalog.md` — **start here.** Every documented component with a one-line
      purpose, grouped by category. Scan it for the name and its synonyms before anything else.
    - https://bestax.io/docs/api — one doc page per shipped component (full props).
    
    Then decide, and **surface the decision to the user**:
    
    - **Exact / synonym match exists** → recommend using it. Don't build a duplicate. (E.g. a small
      colored label/badge/chip → `Tag` / `Tags` already exist.)
    - **Partial overlap** → prefer **composing** the existing pieces inside your new component
      rather than re-implementing them. (E.g. a "profile card" → there's no `ProfileCard`, but
      `Card`, `Image`, `Title`, `SubTitle`, and `Content` exist; build `ProfileCard` to compose them.)
    - **Genuine gap** → build the new component using the pattern below.
    
    State plainly which case applies before writing code, e.g. _"`Tag` already covers a colored
    label — use that instead"_ or _"No `ProfileCard` exists; I'll build one composing the existing
    `Card`/`Image`/`Title` elements."_
    
    ## Composition first
    
    Build from existing components before writing any CSS: `Box`, `Card`, `Title`, `SubTitle`,
    `Icon`, `Block`, `Content`, `Tag`, plus the shared Bulma helper props (spacing, color,
    typography, flexbox). Some compound sub-parts are the exception — `Modal.Card`, `Tabs.Tab`,
    `Message.Body` take **no Bulma helper props**, just `className` + HTML attributes
    plus their own few (`Tabs.Tab` requires `index={i}` and has built-in `disabled` and
    `icon`/`iconLibrary`/`iconVariant`/`iconSize`/`iconFeatures` — don't nest an `<Icon>` there) —
    so put helper props on the parent or on an element inside them, never invent them there.
    (`Card.*` sub-parts do take helper props, like `Table.*`/`Menu.*`/`Hero.*`.) Most "custom components" are a composition function — zero new styles.
    See `examples/stat-card.tsx` for a complete worked example.
    
    Rendering something only the browser knows (the reader's time zone, a `localStorage` value)?
    Wrap it in the library's `ClientOnly` rather than checking `typeof window`: it renders a fallback
    until the page has hydrated, so the server and client markup match. `references/api.md` has the
    details.
    
    A button that shows only an icon (Delete in a table row, Settings in a navbar) is `IconButton`:
    `<IconButton icon="trash" aria-label="Delete" />`, rather than a `Button` holding an `Icon`. The
    glyph goes in `icon` or as the one child (`<Icon name="trash" />`, or an SVG), not both. Its
    types require `aria-label`, or `aria-labelledby` in its place, so name the action, not the picture.
    It takes every `Button` prop, is `type="button"` unless you pass `submit` or `reset`, and
    `isRounded` makes it a circle. Several go in `Buttons`, where it's also `Buttons.IconButton`. For a
    description on hover, wrap it in `Tooltip`, which describes it and doesn't name it.
    
    A button that copies text (a share link, an API key, an install command) is `CopyButton`:
    `<CopyButton value={url} />`, rather than a `Button` calling `navigator.clipboard` yourself. It
    falls back to the copy command where the Clipboard API is missing, reports a failure rather than
    showing "Copied", reads "Copied" for `duration` ms (2000, and `0` keeps it, as on `Toast`), and
    announces each result in a status region it portals, so it can sit last in a `Control` or `Buttons`,
    where it's also `Buttons.CopyButton`. `showLabel={false}` makes it an icon-only `IconButton` named by
    `labels.copy`. Its callbacks are `onCopiedChange` and `onCopyError` (not `onCopy`/`onError`, which
    are DOM events), and an `onClick` that calls `preventDefault()` stops the copy. For a trigger of your
    own, use `useClipboard`.
    
    A button that turns something on or off and stays that way (Bold, Mute, Show archived) is
    `ToggleButton`: use it rather than `Button isActive`, which only draws a shade and sets no
    `aria-pressed`. It's always `type="button"`, holds its own state (`defaultPressed`) or takes
    `pressed` with `onPressedChange`, and fills with `color` (default `link`) only while pressed.
    Its label stays the same in both states, and an icon-only one needs an `aria-label`. A set goes
    in `Buttons hasAddons role="group" aria-label="…"`, where it's also `Buttons.ToggleButton`. A row
    where only one can be on is a radio group, so it's `SegmentedControl` (below), never toggles that
    switch each other off. A setting saved with a form is a `Switch` or a `Checkbox`.
    
    A row of buttons where only one can be on (text alignment, a list or grid view, monthly or yearly
    billing) is `SegmentedControl`: use it rather than `Buttons hasAddons` with `isActive` or a fill
    you move yourself. Give it an `aria-label`, put one `SegmentedControl.Segment value="…"` inside per
    option, and hold the choice with `defaultValue`, or `value` with `onChange(value)`. A screen reader
    hears a radio group, and the single tab stop, the arrow keys, Home and End come built in, so add
    no `onKeyDown` or `role` of your own. An icon-only segment needs its own `aria-label`, as an
    icon-only `ToggleButton` does. The arrow keys check the segment they land on, so `onChange` fires
    on each, and pressing the checked segment keeps it checked. It carries no form value: a choice
    the form submits is `Radios`.
    
    A panel opened from a button (a filter form, share options, an inline edit) is `Popover`: use
    it rather than building one. It anchors the panel, moves focus in and back, and closes on
    Escape and outside presses.
    
    A preview that shows up on hover (a profile card on a username, a summary on a link) is
    `HoverCard`: use it rather than wiring pointer events to a `Popover`. It opens on hover and
    keyboard focus after a delay, lets the pointer move onto the card, closes on Escape, and ignores
    touch unless `openOnTap` is on, which suits only a trigger with no tap action of its own (a
    `Button` with no `onClick`, never a link). Its `trigger` has to be a link or a button, and a trigger in running text takes
    `appendToBody`. A form never goes in one; that's `Popover`.
    
    A menu of actions that opens on a right-click (Rename and Delete on a table row, Archive on a
    card) is `ContextMenu`: use it rather than an `onContextMenu` handler that positions a
    `Dropdown`. It opens at the point, also on Shift+F10, the context menu key and a long press,
    and its items are `ContextMenu.Item` and `ContextMenu.Divider`, the same components as
    `Dropdown.Item` and `Dropdown.Divider`. Its `trigger` is cloned, not wrapped, so a `Table.Tr`
    works, and the menu needs `aria-label`. Put the same items in a visible `Dropdown` as well:
    nothing tells a screen reader user a context menu is there, and on macOS only VoiceOver opens
    it from the keyboard.
    
    A command palette, a search over things to do that opens on ⌘K or Ctrl+K, is
    `Command.Dialog`: `<Command.Dialog shortcut="mod+k" actions={[{ id, label, onSelect }]} />`, or
    built from parts for a server search. Don't hand-build one from `Portal`, `useFocusTrap` and a
    `keydown` listener. Inline, without the modal, it's `Command`.
    
    Building something else that floats? Render it through the library's `Portal` rather than
    `createPortal`: it renders nothing on the server and during hydration, so the server and client
    markup match. `references/api.md` has the details.
    
    Building some other overlay that holds focus until it is dismissed? Use the library's
    `useFocusTrap` rather than a hand-rolled Tab handler: it finds the tab stops the browser visits
    and hands focus back on close. `references/api.md` has the signature and a worked panel.
    
    ## The component spine
    
    Same shape the library itself uses, with all imports from the package. Every reusable
    component gets it — including pure compositions with zero CSS (a heading block, a labeled
    wrapper): extend `BulmaClassesProps`, run your props through `useBulmaClasses`, merge its
    `bulmaHelperClasses` into `className`, and spread the `rest` **it** returns — spreading the raw
    props instead leaks helper props onto the DOM and emits none of their classes. The
    `usePrefixedClassNames` root class is needed only when component-scoped CSS (or a variant
    class) targets it — a zero-CSS composition may omit that call. File at
    `src/components/MyComponent.tsx`:
    
    ```tsx
    import type React from 'react';
    import {
      classNames,
      usePrefixedClassNames,
      useBulmaClasses,
      type BulmaClassesProps,
    } from '@allxsmith/bestax-bulma';
    
    export interface MyComponentProps
      extends
        Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>,
        Omit<BulmaClassesProps, 'color'> {
      color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
    }
    
    export function MyComponent({
      color,
      className,
      children,
      ...props
    }: MyComponentProps) {
      const { bulmaHelperClasses, rest } = useBulmaClasses(props);
      const mainClasses = usePrefixedClassNames('mycomponent', {
        [`is-${color}`]: !!color,
      });
      return (
        <div
          className={classNames(mainClasses, bulmaHelperClasses, className)}
          {...rest}
        >
          {children}
        </div>
      );
    }
    ```
    
    This gives your component the full Bulma helper-prop surface (`m`, `p`, `textAlign`, …) for
    free. `references/api.md` documents the helpers.
    
    ## Styling ladder — use the lowest rung that works
    
    **Rung 1 — helper props only (default).** House rules: never `style={{}}`. Lay children out
    with `Stack` (a column), `Group` (a row that wraps), `Center` or `Flex`, which are flex
    containers already and zero the margins Bulma gives their children, so `gap` is the only space;
    `alignItems`, `justifyContent` and the rest go straight on them. Don't reach for `Box` as a
    plain flex container: it's a padded, shadowed surface. Before writing `style={{ … }}` anywhere,
    translate each declaration:
    
    | 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). On `Title`/`SubTitle`, `as` sets the level and `size` picks it too, so an `<h3>` at size 4 is `as="h3" textSize="4"`       |
    | `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 you'll compose with (`Box`, `Block`, `Title`, `Content`, `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`.
    
    A value with no helper equivalent (`maxWidth: 720`, a one-off gradient) moves you to rung 2 —
    a named class in a stylesheet — never to inline `style`.
    
    **Rung 2 — a plain CSS file**, scoped under the component's class, consuming `--bulma-*`
    variables — never literal colors, so `Theme` and dark mode keep working:
    
    ```css
    /* src/components/MyComponent.css — import from the .tsx file */
    .mycomponent {
      /* component-scoped custom props, initialized from Bulma tokens:
         any ancestor (or Theme) can re-theme by overriding them */
      --mycomponent-radius: var(--bulma-radius);
      --mycomponent-accent: var(--bulma-primary);
      border-radius: var(--mycomponent-radius);
      border: 1px solid var(--bulma-border);
      background: var(--bulma-scheme-main);
      color: var(--bulma-text);
    }
    .mycomponent .mycomponent-value {
      color: var(--mycomponent-accent);
    }
    ```
    
    Caveat: with the prefixed CSS flavor / `ConfigProvider classPrefix`, `usePrefixedClassNames`
    prefixes your classes too — your CSS selectors must match (or build them with plain
    `classNames` instead).
    
    **Rung 3 — real Sass (optional).** `npm i -D sass` — nothing else; Vite compiles imported
    `.scss` zero-config, and `bulma` is resolvable because it's a runtime dependency of
    bestax-bulma. Then the full `register-vars`/`getVar` pattern from
    `references/library-contributor.md` works in-app. Prefixed flavor:
    `@use 'bulma/sass/utilities/initial-variables' with ($class-prefix: 'bestax-')`.
    
    ## Verify in the browser
    
    Types don't see layout. Run `npm run dev`, render the component, and actually look at it:
    vertical centering of inline text (use `display="flex" alignItems="center"`, not line-height
    hacks), balanced padding, nothing clipping, every color/size variant, and **dark mode**
    legibility. Fix what you see, then re-check. No browser available (headless)? Fall back to
    `npm run build` plus a Node `renderToString` smoke render, grep the emitted HTML for the
    expected classes, and flag the visual pass as not done.
    
    ## Tests and stories in an app
    
    The scaffolded app has **no test runner and no Storybook** — do not install or scaffold them
    unasked. If the app already has vitest/jest + Testing Library, write the four test shapes:
    render, prop→class mapping, helper-prop passthrough (`m="3"` → `m-3`), and the
    `ConfigProvider classPrefix` case if the app uses a prefix.
    
    ## Checklist
    
    - [ ] Inventory checked (catalog + bestax.io/docs/api) and the decision surfaced to the user.
    - [ ] All imports from `@allxsmith/bestax-bulma` (no deep/internal paths).
    - [ ] Composition first — existing components + helper props before any CSS; every reusable component gets the spine.
    - [ ] No inline `style={{}}` anywhere — translate via the rung-1 mapping table; values with
          no helper equivalent get a named class (rung 2).
    - [ ] Lowest sufficient ladder rung (helper props → scoped CSS vars → Sass).
    - [ ] All colors/radii derived from `--bulma-*` variables — no literals.
    - [ ] Renders correctly via `npm run dev`, including dark mode.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.