docs: new-component checklist, bounded CLAUDE.md deltas, /pre-pr command

CLAUDE.md

@@ -35,12 +35,13 @@ Enforced by CI (`.github/workflows/ci.yml`):
 - Coverage thresholds from the jest configs: **bulma-ui 99%** (all metrics),
   create-bestax 95% (78% branches).
 - Stale skill catalog fails (`gen:catalog:check`); build, typecheck, lint, format, audit.
+- House conventions fail via `pnpm check:conformance` (error messages name the file and fix);
+  a **React 18/19 matrix** builds and tests bulma-ui on both majors.
 
 Enforced in review (a green CI does **not** check these):
 
-- Every visible/interactive UI change needs a **Storybook story**.
-- Every public API change needs a **docs page update** (`docs/docs/api/...`) before approval.
-- Component/prop changes that affect the skills update `skills/` **in the same PR**.
+- CI only checks that a story and docs page **exist** per component — prop-level changes still
+  need both updated, and skill-affecting changes update `skills/` **in the same PR**.
 - Run `pnpm all` locally before opening a PR.
 
 ## Commits — release-affecting, not cosmetic
@@ -73,8 +74,9 @@ Full versioning details (breaking-change footers, tag formats): `VERSIONING.md`.
 ## Workflow
 
 PRs target `main`; direct pushes to `main` are not allowed. Full contributor guide:
-`CONTRIBUTING.md`. New components should stay within the Bulma spec — propose anything beyond
-it in an issue first.
+`CONTRIBUTING.md`; for a new component, `CONTRIBUTING-COMPONENTS.md` is the end-to-end
+checklist. New components should stay within the Bulma spec — propose anything beyond it in
+an issue first.
 
 AI/LLM surfaces: the docs build publishes an LLM index (see `docs/CLAUDE.md`); the skills are a
 shipped product (see `skills/CLAUDE.md`). This file is also read by **CodeRabbit** (PR reviews)

CONTRIBUTING-COMPONENTS.md

@@ -0,0 +1,58 @@
+# New component checklist
+
+The definition of complete for adding a component to `@allxsmith/bestax-bulma` — for humans
+and AI agents alike. `pnpm check:conformance` and CI enforce most of it; this file is the
+full sequence. Conventions live in the folder `CLAUDE.md`s; templates in
+`skills/bestax-custom-component/references/library-contributor.md`.
+
+## 0. Classify first — everything below forks on this
+
+|                  | Stock Bulma (in the Bulma v1 spec)     | Extra / "Beyond Bulma"                                            |
+| ---------------- | -------------------------------------- | ----------------------------------------------------------------- |
+| Prerequisite     | —                                      | Issue discussion first (component proposal)                       |
+| SCSS             | **None** — Bulma provides the CSS      | Partial required (register-vars pattern)                          |
+| Homepage listing | `docs/src/data/componentCategories.js` | `docs/src/components/EnhancedAddons/index.js` + SVG in `icons.js` |
+
+Before building anything: scan `skills/bestax-custom-component/references/component-catalog.md`
+for an existing component or synonym. If one fits, use or extend it.
+
+## 1. The artifacts
+
+- [ ] `bulma-ui/src/<folder>/Foo.tsx` — helper props via `useBulmaClasses`, own classes via
+      `usePrefixedClassNames`, spread `rest`
+- [ ] `bulma-ui/src/<folder>/__tests__/Foo.test.tsx` — 99% all metrics; must include a
+      `ConfigProvider classPrefix` test (pattern: `Reveal.test.tsx`)
+- [ ] `bulma-ui/src/<folder>/Foo.stories.tsx` — import types from `@storybook/react-vite`;
+      `tags: ['autodocs']`; a `description` on every argType; no inline `style={{}}`
+- [ ] _(extras only)_ `bulma-ui/src/scss/<folder>/_foo.scss` + `@use 'foo';` in that folder's
+      `_index.scss` — see `bulma-ui/src/scss/CLAUDE.md`
+- [ ] `docs/docs/api/<folder>/foo.md` — mirror `docs/docs/api/components/avatar.md`;
+      frontmatter `title:` = the exact exported name (the catalog generator parses it)
+- [ ] Export in `bulma-ui/src/index.ts`, then `pnpm gen:catalog`
+
+## 2. Listing surfaces (the step everyone misses)
+
+- [ ] `### Foo` section on the category guide page (`docs/docs/guides/library/components.md`
+      or `form.md`) — one prose sentence + a `tsx live` example
+- [ ] Homepage: **exactly one** surface per the table above — never both. Plural group
+      containers (`Avatars`) are not listed as cards; the guide page lists them.
+
+## 3. Skills sync (same PR, always)
+
+- [ ] Themeable (SCSS partial or color/size props)? Add rows to
+      `skills/bestax-theming/references/themeable-components.md` and its new `--bulma-*` vars
+      to `css-variables.md`
+- [ ] Changed shared helper props? Update `skills/bestax-custom-component/references/api.md`
+
+## 4. Gates
+
+- [ ] `pnpm check:conformance` and `pnpm gen:catalog:check`
+- [ ] `pnpm all` (build, typecheck, test+coverage, bundle:stats, lint, format, storybook build)
+- [ ] Works on **React 18 and 19** — CI runs both majors; avoid single-major APIs
+- [ ] Visually inspect every variant in Storybook, light and dark mode
+
+## 5. Before opening the PR
+
+- [ ] Re-read your full diff against this checklist — each miss a reviewer catches costs a
+      review round
+- [ ] Conventional commit with scope: `feat(bulma-ui): add Foo`

bulma-ui/CLAUDE.md

@@ -27,6 +27,8 @@ A new or changed component is **five artifacts, not one**. Touch all of:
 
 …then run `pnpm gen:catalog` (CI's `gen:catalog:check` fails if the skill catalog is stale).
 If the change invalidates guidance in `skills/`, update the skill in the same PR.
+For a **new** component, `/CONTRIBUTING-COMPONENTS.md` is the complete checklist — it adds the
+docs listing surfaces and skills sync that CI's `check:conformance` enforces.
 
 The full worked walkthrough (including the SCSS side for extras) is
 `skills/bestax-custom-component/SKILL.md` — follow it rather than improvising.
@@ -42,5 +44,11 @@ The full worked walkthrough (including the SCSS side for extras) is
   widget) need an issue discussion first, and pair with SCSS in `src/scss/`.
 - Tests: jest + ts-jest + Testing Library, in each folder's `__tests__/`. Run one file with
   `pnpm --filter @allxsmith/bestax-bulma exec jest src/elements/__tests__/Button.test.tsx`.
+  The 99% bar is reachable with the techniques in `src/components/__tests__/Reveal.test.tsx`
+  (IntersectionObserver/matchMedia mocks, SSR via `renderToStaticMarkup`).
+- Stories: types from `@storybook/react-vite`; `tags: ['autodocs']`; every argType gets a
+  `description` (meta-test enforced). No inline `style={{}}` in stories/docs examples — helper
+  props (no `gap` helper — space with `m*`/`p*`); legacy inline styles exist, don't copy them.
+- Must build and pass tests on **React 18 and 19** (CI matrix) — avoid single-major APIs.
 - Bundle size is marketing-visible (the READMEs link the live bundlephobia badge) — check `pnpm bundle:stats`
   (writes `dist/stats.html`) when adding anything with real runtime weight.

bulma-ui/src/scss/CLAUDE.md

@@ -49,7 +49,12 @@ Rules the pattern encodes:
 - **Never a raw color/size value** in declarations — derive from Bulma tokens via `cv.getVar()`
   so the extra is themeable exactly like stock Bulma (`--bulma-collapse-border-color: …`).
   This is the contract the `Theme` component and the `bestax-theming` skill rely on.
+- **Register every themable value** — durations, offsets, and insets included, not just colors.
+  Prefer an existing Bulma token (`cv.getVar('radius-rounded')`, never `9999px`); dark mode
+  works only through scheme tokens (`scheme-main`, `text`, `border`) — a hardcoded grey is a
+  dark-mode bug.
 - **Reuse `extras-*` mixins** for transitions, focus outlines, and screen-reader-only content
   instead of re-rolling them (focus style consistency is an a11y requirement).
 - New CSS variables should be documented in
-  `skills/bestax-theming/references/css-variables.md` alongside the docs page.
+  `skills/bestax-theming/references/css-variables.md`, and the component's rows added to
+  `skills/bestax-theming/references/themeable-components.md`, in the same PR.

docs/CLAUDE.md

@@ -33,8 +33,11 @@ it, so a novel non-standard `package.json` key and extra release churn weren't w
 
 ## Conventions
 
-- Pages carry frontmatter (`title`, `sidebar_position`); API pages use consistent sections
-  (props table, examples) — mirror a sibling page, don't invent a new structure.
+- API pages mirror `docs/api/components/avatar.md` (the house exemplar), not older siblings;
+  `check:conformance` enforces the required sections. Frontmatter `title:` = the exported
+  name, and the first `## Overview` sentence becomes its catalog one-liner (`gen:catalog`).
+- No inline `style={{}}` in examples — use `Block`/helper props; there is no `gap` helper,
+  space children with `m*`/`p*`.
 - Code examples must compile against the current library API; when a component changes, its
   docs page changes in the same PR (CONTRIBUTING requires docs before approval).
 - Markdown is prettier-formatted (`pnpm format:check` covers `md`/`mdx`).