create-bestax 3.1.3 → 3.2.0

package/templates/skills/bestax-custom-component/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: bestax-custom-component
-description: Build a new custom Bulma "extra" component for @allxsmith/bestax-bulma — a React + TypeScript component with Bulma v1 SCSS (the CSS-variable pattern), Storybook stories, tests, and docs. Use when adding a component that goes beyond stock Bulma (like Dialog, Carousel, Switch, Slider, Rate, Taginput), or when extending an existing one to match the library's conventions.
+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 bestax-bulma component
+# Building a custom component the bestax way
 
-This skill teaches the end-to-end pattern the library uses for its custom "extra"
-components — the ones that aren't part of stock Bulma. Follow it whenever you add a new
-component to `@allxsmith/bestax-bulma`, or refactor a component to match house style.
+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.
 
-## Use when
+## Which context are you in?
 
-- Creating a new component beyond stock Bulma (an interactive widget, a composed element).
-- Writing the component's SCSS and you need it to follow the **Bulma v1 CSS-variable pattern**
-  (`register-vars` / `getVar`, `--bulma-*` custom properties, the class prefix).
-- Wiring a component into the package exports, the SCSS bundle, Storybook, tests, and docs.
+- **The bestax monorepo** (the repo contains `bulma-ui/src/`) → follow
+  `references/library-contributor.md` instead of this file: five-file layout, SCSS partial,
+  stories, jest 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.
 
@@ -30,359 +30,130 @@ call.
 Where to look:
 
 - `references/component-catalog.md` — **start here.** Every documented component with a one-line
-  purpose, grouped by category (generated from the API docs). Scan it for the name and its
-  synonyms before anything else.
-- `bulma-ui/src/index.ts` — the full export list; check here for anything not yet documented (e.g.
-  raw `*Base` form variants) that the catalog omits.
-- `docs/docs/api/{elements,components,form}/` — one doc page per shipped component (full props).
-- Storybook titles — `Elements/*`, `Components/*`, `Form/*`.
+  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 or extending** 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.)
+- **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."_
 
-## File layout
+## Composition first
 
-Every custom component has five files. Mirror the existing names exactly (PascalCase TSX,
-`_kebab.scss` partial):
+Build from existing components before writing any CSS: `Box`, `Card`, `Title`, `SubTitle`,
+`Icon`, `Block`, `Content`, `Tag`, plus the Bulma helper props every component accepts (spacing,
+color, typography, flexbox). Most "custom components" are a composition function — zero new
+styles. See `examples/stat-card.tsx` for a complete worked example.
 
-```
-bulma-ui/src/components/MyComponent.tsx              # React + TS component
-bulma-ui/src/components/MyComponent.stories.tsx      # Storybook stories
-bulma-ui/src/components/__tests__/MyComponent.test.tsx  # Jest + RTL tests
-bulma-ui/src/scss/components/_mycomponent.scss       # SCSS partial
-docs/docs/api/components/mycomponent.md              # Docusaurus docs page
-```
-
-Then wire two index files (see **Wiring & build**).
+## The component spine
 
-## Component template
-
-Components use `forwardRef`, accept Bulma helper props via `BulmaClassesProps`, run them
-through `useBulmaClasses`, build their own classes with `usePrefixedClassNames`, and merge
-everything with `classNames`. Spread `rest` (the non-helper props) onto the DOM node.
+Same shape the library itself uses, with all imports from the package. File at
+`src/components/MyComponent.tsx`:
 
 ```tsx
-import React, { forwardRef } from 'react';
-import { classNames, usePrefixedClassNames } from '../helpers/classNames';
-import { useBulmaClasses, BulmaClassesProps } from '../helpers/useBulmaClasses';
-
-export type MyComponentColor =
-  'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
-
-/**
- * Props for the MyComponent component.
- *
- * @property {MyComponentColor} [color] - Bulma color modifier.
- * @property {'small' | 'medium' | 'large'} [size] - Size modifier.
- * @property {boolean} [isActive] - Whether the component is active.
- */
+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?: MyComponentColor;
-  size?: 'small' | 'medium' | 'large';
-  isActive?: boolean;
+  color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
 }
 
-/**
- * MyComponent — short description of what it does.
- *
- * @example
- * <MyComponent color="primary" size="large" isActive>Hello</MyComponent>
- */
-export const MyComponent = forwardRef<HTMLDivElement, MyComponentProps>(
-  ({ color, size, isActive, className, children, ...props }, ref) => {
-    // 1. Pull Bulma helper classes (m/p, text*, display, etc.) out of props.
-    const { bulmaHelperClasses, rest } = useBulmaClasses(props);
-
-    // 2. Build this component's own classes (respects the ConfigProvider classPrefix).
-    const mainClasses = usePrefixedClassNames('mycomponent', {
-      [`is-${color}`]: !!color,
-      [`is-${size}`]: !!size,
-      'is-active': !!isActive,
-    });
-
-    // 3. Merge: own classes + helper classes + caller className.
-    const combined = classNames(mainClasses, bulmaHelperClasses, className);
-
-    return (
-      <div ref={ref} className={combined} {...rest}>
-        {children}
-      </div>
-    );
-  }
-);
-
-MyComponent.displayName = 'MyComponent';
-
-export default MyComponent;
-```
-
-Rules that keep components consistent:
-
-- **Always `Omit<…, 'color'>`** from both `HTMLAttributes` and `BulmaClassesProps` when the
-  component exposes its own typed `color`, so the native/helper `color` doesn't collide.
-- **Never hand-build class strings.** Use `usePrefixedClassNames(base, conditionalMap)` so the
-  optional `classPrefix` from `ConfigProvider` is honored, then `classNames(...)` to merge.
-- **Spread `rest`, not `props`**, onto the DOM node — `useBulmaClasses` has already stripped the
-  helper props out of `rest`, so they don't leak to the DOM as invalid attributes.
-- **Set `displayName`** on `forwardRef` components (needed for tests and Storybook autodocs).
-- **Element sizing uses an inline `'small' | 'medium' | 'large'` union**, mapped to `is-small` /
-  `is-medium` / `is-large` (see `Tabs.tsx`, `Control.tsx`). Do **not** reach for the `validSizes`
-  constant — that one is `'0'…'6' | 'auto'` and exists for **spacing** helpers, not element size.
-- **Format before you lint.** The repo enforces Prettier and ESLint fails on unformatted code.
-  Run `pnpm exec prettier --write` on your new files (or `pnpm format` from the repo root) before
-  `pnpm lint`. Copy snippets as a starting point, then let Prettier normalize them.
-
-See `references/api.md` for the full helper API and `references/patterns.md` for the complete
-Dialog walkthrough.
-
-## SCSS pattern (required)
-
-This is the library's house convention — **the Bulma v1 CSS-variable pattern**. Do not write
-plain hard-coded CSS or homebrew `--mycomponent-*` variables. Import Bulma's utilities, declare
-SCSS vars with `!default`, register them as `--bulma-*` custom properties on the root selector
-with `cv.register-vars`, then consume them with `cv.getVar`. Prefix every selector with
-`iv.$class-prefix`.
-
-```scss
-// bulma-ui/src/scss/components/_mycomponent.scss
-@use 'bulma/sass/utilities/initial-variables' as iv;
-@use 'bulma/sass/utilities/css-variables' as cv;
-
-// 1. SCSS variables, overridable, referencing Bulma vars via cv.getVar.
-$mycomponent-radius: cv.getVar('radius') !default;
-$mycomponent-background: cv.getVar('scheme-main') !default;
-$mycomponent-color: cv.getVar('text') !default;
-$mycomponent-padding: 1rem !default;
-
-// 2. Register them as runtime --bulma-* custom properties on the root selector.
-.#{iv.$class-prefix}mycomponent {
-  @include cv.register-vars(
-    (
-      'mycomponent-radius': #{$mycomponent-radius},
-      'mycomponent-background': #{$mycomponent-background},
-      'mycomponent-color': #{$mycomponent-color},
-      'mycomponent-padding': #{$mycomponent-padding},
-    )
+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>
   );
 }
+```
 
-// 3. Consume via cv.getVar. Prefix every selector with iv.$class-prefix.
-.#{iv.$class-prefix}mycomponent {
-  background-color: cv.getVar('mycomponent-background');
-  border-radius: cv.getVar('mycomponent-radius');
-  color: cv.getVar('mycomponent-color');
-  padding: cv.getVar('mycomponent-padding');
-}
-
-// Color variants reuse Bulma's registered color vars.
-.#{iv.$class-prefix}mycomponent.#{iv.$class-prefix}is-primary {
-  background-color: cv.getVar('primary');
-  color: cv.getVar('primary-invert');
+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={{}}`. Layout with
+`Block`/`Box` and `display="flex"`, `flexDirection`, `alignItems`, `justifyContent`. There is
+**no `gap` helper** — space children with `m*`/`p*` margins instead.
+
+**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);
 }
-
-// Respect reduced-motion if you animate.
-@media (prefers-reduced-motion: reduce) {
-  .#{iv.$class-prefix}mycomponent {
-    animation: none;
-  }
+.mycomponent .mycomponent-value {
+  color: var(--mycomponent-accent);
 }
 ```
 
-Why this matters: registering vars makes the component themeable at runtime (the docs site and
-`Theme`/`ConfigProvider` providers override `--bulma-*` properties), and the `iv.$class-prefix` keeps
-the component working when consumers opt into a class prefix to avoid collisions.
-
-The canonical reference file is `bulma-ui/src/scss/components/_dialog.scss`.
-
-## Stories
-
-`MyComponent.stories.tsx` beside the component. Use `tags: ['autodocs']` so the JSDoc becomes
-the docs page, declare `argTypes`, and write one named `function`-style render per variant.
-
-```tsx
-import type { Meta, StoryObj } from '@storybook/react';
-import { MyComponent } from './MyComponent';
-
-const meta: Meta<typeof MyComponent> = {
-  title: 'Components/MyComponent',
-  component: MyComponent,
-  tags: ['autodocs'],
-  argTypes: {
-    color: {
-      control: 'select',
-      options: ['primary', 'link', 'info', 'success', 'warning', 'danger'],
-    },
-    isActive: { control: 'boolean' },
-  },
-};
-export default meta;
-type Story = StoryObj<typeof MyComponent>;
-
-export const Default: Story = {
-  render: function DefaultExample() {
-    return <MyComponent>Default</MyComponent>;
-  },
-};
-
-export const Colors: Story = {
-  render: function ColorsExample() {
-    return (
-      <>
-        <MyComponent color="primary">Primary</MyComponent>
-        <MyComponent color="danger">Danger</MyComponent>
-      </>
-    );
-  },
-};
-```
-
-## Tests
-
-`__tests__/MyComponent.test.tsx`, Jest + `@testing-library/react`. Cover render, each prop →
-class mapping, the helper-prop passthrough, ref forwarding, and any interaction/a11y.
-
-```tsx
-import { render, screen } from '@testing-library/react';
-import { createRef } from 'react';
-import { MyComponent } from '../MyComponent';
-
-describe('MyComponent', () => {
-  it('renders children', () => {
-    render(<MyComponent>Hello</MyComponent>);
-    expect(screen.getByText('Hello')).toBeInTheDocument();
-  });
-
-  it('applies the color modifier', () => {
-    render(<MyComponent color="primary">x</MyComponent>);
-    expect(screen.getByText('x')).toHaveClass('mycomponent', 'is-primary');
-  });
-
-  it('passes Bulma helper props through', () => {
-    render(<MyComponent m="3">x</MyComponent>);
-    expect(screen.getByText('x')).toHaveClass('m-3');
-  });
-
-  it('forwards the ref', () => {
-    const ref = createRef<HTMLDivElement>();
-    render(<MyComponent ref={ref}>x</MyComponent>);
-    expect(ref.current).toBeInstanceOf(HTMLDivElement);
-  });
-});
-```
-
-## Docs page
-
-`docs/docs/api/components/mycomponent.md` — Overview, Import, a Props table, and `Usage` with
-live examples. Live code blocks use the ` ```tsx live ` fence (Docusaurus live-codeblock).
-
-````md
----
-title: MyComponent
-sidebar_label: MyComponent
----
-
-# MyComponent
-
-## Overview
-
-Short description of the component.
-
-## Import
-
-```tsx
-import { MyComponent } from '@allxsmith/bestax-bulma';
-```
-
-## Props
-
-| Prop       | Type                         | Default | Description           |
-| ---------- | ---------------------------- | ------- | --------------------- |
-| `color`    | `'primary' \| 'link' \| ...` | —       | Bulma color modifier. |
-| `isActive` | `boolean`                    | `false` | Active state.         |
-
-## Usage
+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).
 
-### Default
-
-```tsx live
-<MyComponent>Hello</MyComponent>
-```
-````
-
-> Note: the Docusaurus docs load the **built** dist CSS. After SCSS changes, run
-> `cd bulma-ui && pnpm build` before the new styles show up in the docs site (Storybook
-> compiles SCSS live and does not need this).
-
-## Wiring & build
-
-Two index files must be updated or the component won't ship:
-
-1. **Package export** — add to `bulma-ui/src/index.ts`, in the **components** group (the file
-   groups exports by directory — keep yours next to the other `./components/*` lines):
-   ```ts
-   export * from './components/MyComponent';
-   ```
-2. **SCSS bundle** — add to `bulma-ui/src/scss/components/_index.scss`:
-   ```scss
-   @use 'mycomponent';
-   ```
-
-Then build and verify:
-
-```sh
-cd bulma-ui
-pnpm exec prettier --write src/components/MyComponent.tsx src/scss/components/_mycomponent.scss
-pnpm lint
-pnpm test
-pnpm build      # compiles JS + the bestax/extras CSS bundles
-```
+**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-')`.
 
-## Visually inspect it in a browser
+## Verify in the browser
 
-Types and unit tests don't see layout. **Render the component and actually look at it** before
-you call it done — spacing, padding, vertical centering, alignment, and every variant/state
-(colors, sizes, hover/active, dark mode). Visual bugs hide from `tsc` and `@testing-library`.
+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.
 
-1. Run a surface that renders it: `pnpm storybook` (compiles SCSS live) or the docs dev server.
-2. Open the component and inspect it. If a browser-automation tool (claude-in-chrome, Playwright)
-   is available, drive the browser and screenshot each variant; otherwise open it yourself and
-   eyeball it.
-3. Check the usual offenders:
-   - **Vertical centering of inline text** — `display: inline-block` + `line-height: 1` makes
-     text sit low. For chips/labels/buttons use `display: inline-flex; align-items: center;
-justify-content: center;` with a normal `line-height` (Bulma's `Tag` is the reference).
-   - Padding/gaps look balanced; nothing clips or overflows.
-   - Every color/size variant renders; dark mode is legible.
+## Tests and stories in an app
 
-Fix what you see, then re-inspect. A green test suite with a misaligned component is not done.
+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
 
-- [ ] **Checked the inventory first** — searched `src/index.ts` / docs / Storybook for an existing
-      match or synonym, and told the user (reuse/extend it, or confirm there's a genuine gap).
-- [ ] `MyComponent.tsx` — `forwardRef`, `Omit<…, 'color'>`, `useBulmaClasses`,
-      `usePrefixedClassNames`, `classNames`, spread `rest`, `displayName` set.
-- [ ] `_mycomponent.scss` — `@use` Bulma utilities, `$vars !default`, `cv.register-vars`,
-      `cv.getVar`, every selector prefixed with `iv.$class-prefix`.
-- [ ] `MyComponent.stories.tsx` — `tags: ['autodocs']`, `argTypes`, one story per variant.
-- [ ] `__tests__/MyComponent.test.tsx` — render, prop→class, helper passthrough, ref.
-- [ ] `docs/docs/api/components/mycomponent.md` — Overview / Import / Props / `tsx live`.
-- [ ] `src/index.ts` exports the component (in the `./components/*` group).
-- [ ] `scss/components/_index.scss` `@use`s the partial.
-- [ ] Prettier-formatted, then `pnpm lint && pnpm test && pnpm build` all pass.
-- [ ] **Rendered and visually inspected in a browser** — centering/spacing/variants all look
-      right (not just green tests).
+- [ ] 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.
+- [ ] No inline `style={{}}` anywhere.
+- [ ] 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.

package/templates/skills/bestax-custom-component/examples/stat-card.tsx

@@ -0,0 +1,101 @@
+// StatCard — the app-side worked example for the bestax-custom-component skill.
+// (The library-contributor counterpart is Dialog, in references/patterns.md.)
+//
+// Context: an app depending on @allxsmith/bestax-bulma (e.g. `npm create bestax`).
+// Everything imports from the package; no monorepo wiring, no Sass pipeline.
+//
+// It demonstrates the two lowest rungs of the styling ladder:
+//   Rung 1 — composition + helper props only (StatCard): Box/Title/Icon plus
+//            flexbox and spacing helper props. No CSS written at all.
+//   Rung 2 — a small scoped CSS file consuming --bulma-* variables (the
+//            commented block at the bottom) for the one thing helper props
+//            can't do (an accent border), keeping Theme + dark mode working.
+import type React from 'react';
+import {
+  Box,
+  Title,
+  Icon,
+  classNames,
+  usePrefixedClassNames,
+  useBulmaClasses,
+  type BulmaClassesProps,
+} from '@allxsmith/bestax-bulma';
+
+export interface StatCardProps
+  extends
+    Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>,
+    Omit<BulmaClassesProps, 'color'> {
+  /** Metric label, e.g. "Active users". */
+  label: string;
+  /** The headline value, e.g. "12,481". */
+  value: string;
+  /** Icon name (Font Awesome by default), e.g. "users". */
+  icon?: string;
+  /** Bulma color for the icon + accent. */
+  color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
+}
+
+export function StatCard({
+  label,
+  value,
+  icon,
+  color = 'primary',
+  className,
+  ...props
+}: StatCardProps) {
+  // The library's own spine, via public exports: helper props in, classes out.
+  const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+  const mainClasses = usePrefixedClassNames('statcard', {
+    [`is-${color}`]: !!color,
+  });
+
+  return (
+    <Box
+      className={classNames(mainClasses, bulmaHelperClasses, className)}
+      // Rung 1: layout entirely with helper props — no style={{}}, no CSS.
+      display="flex"
+      alignItems="center"
+      p="4"
+      {...rest}
+    >
+      {icon && (
+        <Icon
+          name={icon}
+          size="large"
+          textColor={color}
+          mr="4"
+          ariaLabel={`${label} icon`}
+        />
+      )}
+      {/* No `gap` helper exists — space siblings with margin props (mr above). */}
+      <div>
+        {/* as="p": the sizes are visual scale, not document structure — a bare
+            <Title size> renders a heading and breaks the page outline. */}
+        <Title as="p" size="6" textColor="grey" mb="1">
+          {label}
+        </Title>
+        <Title as="p" size="3" mb="0">
+          {value}
+        </Title>
+      </div>
+    </Box>
+  );
+}
+
+// Rung 2 (optional) — src/components/StatCard.css, imported from this file:
+//
+//   .statcard {
+//     /* Component-scoped custom props initialized from Bulma tokens, so any
+//        ancestor (or <Theme>) can re-theme the card by overriding them. */
+//     --statcard-accent: var(--bulma-primary);
+//     --statcard-radius: var(--bulma-radius);
+//     border-left: 0.25rem solid var(--statcard-accent);
+//     border-radius: var(--statcard-radius);
+//   }
+//   .statcard.is-success { --statcard-accent: var(--bulma-success); }
+//   .statcard.is-danger  { --statcard-accent: var(--bulma-danger);  }
+//
+// Only --bulma-*-derived values — never literal colors — so dark mode and
+// Theme overrides keep working. Caveat: if the app uses the prefixed CSS
+// flavor / ConfigProvider classPrefix, usePrefixedClassNames renders
+// `bestax-statcard`; adjust the selectors (or use plain classNames).

package/templates/skills/bestax-custom-component/references/api.md

@@ -1,6 +1,11 @@
 # Reference: helper APIs for building components
 
-The shared helpers live in `bulma-ui/src/helpers/`. Import them from there in components.
+Everything below is public API. Where to import from depends on your context:
+
+| Context                                       | Import from                                      |
+| --------------------------------------------- | ------------------------------------------------ |
+| An app depending on `@allxsmith/bestax-bulma` | `'@allxsmith/bestax-bulma'`                      |
+| Inside the bestax monorepo (`bulma-ui/src/`)  | Relative paths — `'../helpers/classNames'`, etc. |
 
 ## `useBulmaClasses(props)` — `helpers/useBulmaClasses.tsx`
 
@@ -72,6 +77,10 @@ hard-coding values.
 @use 'bulma/sass/utilities/css-variables' as cv; // cv.getVar, cv.register-vars
 ```
 
+In an app these work too (styling-ladder rung 3 in `SKILL.md`): `npm i -D sass` and Vite
+compiles imported `.scss` zero-config — `bulma` resolves because it's a runtime dependency of
+bestax-bulma.
+
 - `iv.$class-prefix` — the configurable class prefix; prepend to every selector.
 - `cv.getVar("name")` — emits `var(--bulma-name)`; use for both Bulma vars (`"primary"`,
   `"radius"`, `"scheme-main"`, `"text"`) and your own registered vars.

package/templates/skills/bestax-custom-component/references/component-catalog.md

@@ -19,7 +19,7 @@ instead of hand-writing markup.
 - Raw `*Base` form exports (`InputBase`, `SelectBase`, `TextAreaBase`, …) are
   escape-hatch variants of the convenience wrappers above them; see the Form docs.
 
-81 documented components. Generated from the API docs — every exported
+87 documented components. Generated from the API docs — every exported
 component is guaranteed to appear (the generator fails if one lacks an API page).
 
 ## Elements
@@ -57,6 +57,9 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 
 ## Components
 
+- [Avatar](https://bestax.io/docs/api/components/avatar) — The `Avatar` component represents a person or entity as a compact image.
+- [Avatars](https://bestax.io/docs/api/components/avatars) — The `Avatars` component renders an overlapping/stacked group of `Avatar`s, the "members" list pattern.
+- [Badge](https://bestax.io/docs/api/components/badge) — The `Badge` component is a small status/count indicator overlaid on the corner of another element, or rendered standalone.
 - [Breadcrumb](https://bestax.io/docs/api/components/breadcrumb) — The `Breadcrumb` component renders a Bulma-styled breadcrumb navigation.
 - [Card](https://bestax.io/docs/api/components/card) — The `Card` component renders a Bulma-styled card with optional header, image, content, and footer.
 - [Carousel](https://bestax.io/docs/api/components/carousel) — The `Carousel` component provides an image/content slider with navigation arrows and indicators.
@@ -70,6 +73,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Navbar](https://bestax.io/docs/api/components/navbar) — The `Navbar` component implements Bulma's powerful, responsive navigation bar for your Bulma React UI.
 - [Pagination](https://bestax.io/docs/api/components/pagination) — The `Pagination` component provides a flexible, composable Bulma pagination navigation for your Bulma React UI.
 - [Panel](https://bestax.io/docs/api/components/panel) — The `Panel` component implements Bulma's versatile panel block for React.
+- [Reveal](https://bestax.io/docs/api/components/reveal) — The `Reveal` component animates its content into view as it scrolls into the viewport, backed by `IntersectionObserver`.
 - [Sidebar](https://bestax.io/docs/api/components/sidebar) — The `Sidebar` component provides a slide-out navigation panel that appears from the left or right side of the screen.
 - [Steps](https://bestax.io/docs/api/components/steps) — The `Steps` component provides a multi-step progress indicator for wizard flows, checkout processes, or any multi-step workflow.
 - [Tabs](https://bestax.io/docs/api/components/tabs) — The `Tabs` component provides flexible and fully-featured Bulma tab navigation for your Bulma React UI.
@@ -121,5 +125,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 
 - [ConfigProvider](https://bestax.io/docs/api/helpers/config) — The `ConfigProvider` component provides a React context for configuring global settings across all Bulma UI components.
 - [Theme](https://bestax.io/docs/api/helpers/theme) — The `Theme` component provides a powerful way to customize Bulma's appearance using CSS custom properties (CSS variables).
+- [Valid value constants](https://bestax.io/docs/api/helpers/valid-values) — The `valid*` constant arrays enumerate every accepted value for the shared Bulma helper props — public API you can import to build prop types and validation.
 - [classNames](https://bestax.io/docs/api/helpers/classnames) — `classNames` is a utility function for conditionally joining class names together.
 - [useBulmaClasses](https://bestax.io/docs/api/helpers/usebulmaclasses) — `useBulmaClasses` is a custom React hook that generates Bulma helper class strings from a set of props.
+- [usePrefixedClassNames](https://bestax.io/docs/api/helpers/useprefixedclassnames) — `usePrefixedClassNames` builds a component class string that honors the `classPrefix` from `ConfigProvider` — the hook every bestax component uses for its own…