From 607146d35b7227ee8b86ca10dda2126a1c51b603 Mon Sep 17 00:00:00 2001 From: Alex Smith Date: Thu, 9 Jul 2026 21:21:34 -0400 Subject: [PATCH] docs: add the new-component checklist, bounded CLAUDE.md deltas, and a /pre-pr command CONTRIBUTING-COMPONENTS.md is the machine-followable definition of complete for a new component (58 lines, checkbox/table). CLAUDE.md layers gain only what review rounds on PR #257 proved missing; net growth across the four files is ~11% after pruning now-CI-covered review rules. --- CLAUDE.md | 12 ++++---- CONTRIBUTING-COMPONENTS.md | 58 +++++++++++++++++++++++++++++++++++++ bulma-ui/CLAUDE.md | 8 +++++ bulma-ui/src/scss/CLAUDE.md | 7 ++++- docs/CLAUDE.md | 7 +++-- 5 files changed, 84 insertions(+), 8 deletions(-) create mode 100644 CONTRIBUTING-COMPONENTS.md diff --git a/CLAUDE.md b/CLAUDE.md index 29cd70184..636c9b049 100644 --- a/CLAUDE.md +++ b/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) diff --git a/CONTRIBUTING-COMPONENTS.md b/CONTRIBUTING-COMPONENTS.md new file mode 100644 index 000000000..4508fb345 --- /dev/null +++ b/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//Foo.tsx` — helper props via `useBulmaClasses`, own classes via + `usePrefixedClassNames`, spread `rest` +- [ ] `bulma-ui/src//__tests__/Foo.test.tsx` — 99% all metrics; must include a + `ConfigProvider classPrefix` test (pattern: `Reveal.test.tsx`) +- [ ] `bulma-ui/src//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//_foo.scss` + `@use 'foo';` in that folder's + `_index.scss` — see `bulma-ui/src/scss/CLAUDE.md` +- [ ] `docs/docs/api//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` diff --git a/bulma-ui/CLAUDE.md b/bulma-ui/CLAUDE.md index f4fc1dbfb..e0d5c380c 100644 --- a/bulma-ui/CLAUDE.md +++ b/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. diff --git a/bulma-ui/src/scss/CLAUDE.md b/bulma-ui/src/scss/CLAUDE.md index 84b4236a7..ddb35b63a 100644 --- a/bulma-ui/src/scss/CLAUDE.md +++ b/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. diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md index a80ea6d96..77d87164b 100644 --- a/docs/CLAUDE.md +++ b/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`).