bestax / bulma-ui
CLAUDE.md14 starsChanged 8 days agoMITView on GitHub
The component library. Rollup builds ESM + CJS + types into dist/; src/scss ships in the npm package so consumers can build the styles themselves. A new or changed component is five artifacts, not one. Touch all of: <!-- bestax:count-ok: the list immediately below is the definition --> …then run pnpm gen (regenerates the API pages' generated regions and the skill catalog; CI's gen:catalog:check and check:conformance fail if either is stale). If the change invalidates guidance in skills/, update the…
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- bulma-ui/AGENTS.mdAGENTS.md
- bestax-mcp/CLAUDE.mdCLAUDE.md
- bestax-migrate/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- create-bestax/CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- eslint-plugin/CLAUDE.mdCLAUDE.md
- .github/CLAUDE.mdCLAUDE.md
- skills/CLAUDE.mdCLAUDE.md
- templates/CLAUDE.mdCLAUDE.md
- bulma-ui/llms.txtllms.txt
- bestax-custom-componentSkill
- bestax-formSkill
- bestax-iconsSkill
- bestax-layout-scaffoldSkill
- bestax-migrateSkill
- bestax-optimizeSkill
- bestax-themingSkill
The file
We split this CLAUDE.md into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
If the change invalidates guidance in skills/, update the skill in the same PR.
- Very specific: line 127
Reuse before writing: Read src/helpers/, src/form/FormContext.tsx and the nearest component first.
- Very specific: line 136
Every component routes its Bulma helper props through useBulmaClasses and forwards ...rest.
- Very specific: line 138
TSDoc is the docs source, not a comment: Every <Foo>Props member needs an inline / … */ — scripts/gen-api-docs.mjs renders those into the …
- Distinctive: line 200
Must pass tests on React 18 and 19 (CI matrix) — avoid single-major APIs.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
bulma-ui — @allxsmith/bestax-bulma
The component library. Rollup builds ESM + CJS + types into dist/; src/scss ships in the
npm package so consumers can build the styles themselves.
Source map (each folder has its own CLAUDE.md with the real rules)
src/elements/— simple single-purpose Bulma elements (Button, Box, Icon, …)src/components/— composite/interactive widgets (Navbar, Modal, …) + bestax extras (Carousel, Dialog, …)src/form/— form controls on Bulma's Field/Control modelsrc/layout/— page structure (Container, Section, Hero, …)src/columns/— flexbox column system;src/grid/— CSS Grid systemsrc/helpers/— the shared helper-prop system (useBulmaClasses),Theme,Configsrc/scss/— SCSS for the "extras" (components beyond stock Bulma) + flavor buildssrc/skill-examples/— Storybook stories showcasing agent-generated output of theskills/src/index.ts— the public API; everything exported here is public forever (semver)
The component anatomy rule
A new or changed component is five artifacts, not one. Touch all of: <!-- bestax:count-ok: the list immediately below is the definition -->
src/<folder>/Foo.tsx— the componentsrc/<folder>/__tests__/Foo.test.tsx— tests (coverage threshold: 99%,vitest.config.ts)src/<folder>/Foo.stories.tsx— Storybook storydocs/docs/api/<folder>/foo.md— the API docs pagesrc/index.ts— the export
…then run pnpm gen (regenerates the API pages' generated regions and the skill catalog;
CI's gen:catalog:check and check:conformance fail if either 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/references/library-contributor.md — follow it rather than
improvising.
The ./constants subpath
exports["./constants"] serves src/helpers/bulmaClassHelpers.ts on its own,
as dist/constants.cjs and dist/constants.esm.js, so tooling can read the
helper value tuples (validColors, validTextSizes, …) without loading React
or any component. @allxsmith/eslint-plugin-bestax validates against them that
way rather than copying them.
It serves that module WHOLE, which is wider than "the value tuples": it also
carries createBulmaClassHelpers, which is @internal, and cursorClasses,
which the package root does not re-export. Read that as the subpath's actual
contract rather than an oversight, and do not reach for stripInternal to
narrow it — @internal marks props on Button, Link, LinkButton,
Navbar and Avatar as well, so turning it on would drop those from the
published component types, which is a change to the library's public surface
and wants its own review. The narrowing that would be free is a second source
file, and that would split the cursor tuple from the classes it maps to, which
is the drift this file exists to prevent.
These keep it working, and each of them failed once:
- That file must stay import-free, and nothing relies on discipline alone to
keep it that way. The entry has no
resolve(), so an extensionless relative import fails the bundle outright. It keeps the main bundle'sexternal, so a futureuseMemoin it cannot inline React into a bundle whose whole point is not needing React, and the React-free assertion catches that anyway. An import rollup resolves on its own is caught by the declaration check the.d.ctsrule below depends on. - The CommonJS artifact must be
constants.cjs, notconstants.cjs.js. This package is"type": "module", so Node reads a.jsfile as ESM whatever the bundle's format is, and a bundle writingexports.x = …cannot load as CommonJS under that reading. State it as the defect rather than as a symptom: what a caller actually sees varies with the bundle's own code and the runtime — this package's bundles throw, and packages exist that load with a populated namespace instead — so any prediction about the symptom dates quickly. The reason to use.cjsdoes not depend on which one appears. - The emitted declarations need
.json every relative specifier, added by a build step.tscwrites them exactly as the source spells them, and this package is"type": "module", so TypeScript reads a.d.tsas ESM where an extensionless specifier does not resolve — every re-export failed and the root had no usable types at all (#696). Markingdist/typesCommonJS also makes them resolve and was rejected: it would describe a CommonJS module while the bundle is ESM, so a default import typechecks and then throws at runtime. The step runs fromcloseBundleat the main config's level, because the declarations are re-emitted per output and rollup writes a config's outputs concurrently. - Each condition needs its OWN
types, and therequireone must beconstants.d.cts. The same rule, one layer up and less visible: a.d.tsin a"type": "module"package is read as ESM by TypeScript, so amodule: node16CommonJS consumer answered the subpath with TS1479 while the file the require condition points at loaded perfectly. Runtime and types each need the extension that says what they are. The.d.ctsis written by a rollup hook as a VERBATIM COPY of the declaration, not as a re-export of it, because a.d.ctsre-exporting from a.d.tshits the identical error one level down. Copying is only sound while the source module imports nothing, which is the import-free rule above; the build andscripts/constants-subpath.test.mjsboth refuse if that stops being true, and the test typechecks a real node16 CommonJS consumer rather than asserting the map's shape.
Naming and reuse
A new component or prop takes the names its siblings already use, and builds on the shared hooks rather than writing its own. Consistent names are what let a reader, or an agent reading the types, guess one component's API from another's, and a copied hook drifts from the original the first time either one is fixed.
- State props take the shape the newest components use. Open state is
open,defaultOpenandonOpenChange(open)(Popover, Collapse, Command, Combobox, HoverCard). A selected index or value isvalue,defaultValueandonChange(value)(Tabs, Combobox), notindexoractiveIndex; Carousel and Steps name their positionvaluetoo. Any other controlled state isx,defaultXandonXChange(TreeView'sselectedandexpanded). Modal'sactiveand Dialog's and Sidebar'sisOpencame first; don't copy them, and renaming them waits for a major. - A boolean that sets a Bulma modifier class is named after the class:
isRoundedforis-rounded,hasAddonsforhas-addons. A behaviour switch takes the native attribute's name or the one a sibling already uses (disabled,closeOnEscape, Sidebar'soverlay). - A container that lays out several standalone components takes their name in the plural:
Buttons, Tags, Avatars, Collapses, Checkboxes, Radios. A
.Grouppart is for one unit made of pieces (Kbd.Group, a key combination) or a section inside a component (Command.Group, Combobox.Group). - A layout container takes the name of the layout it draws: Stack, Group, Center and Flex lay
out any children, so they aren't named for what they hold. The top-level
Groupis the row of that family, neither a plural nor a.Grouppart, and the rule above doesn't rename it. colortakes Bulma's color names andsizethe'small' | 'medium' | 'large'union. Text a caller may want to translate goes in the same kind of prop the nearest sibling uses (the pickers'labels), and anything locale-aware readsLocaleProvider.- Class names, Sass variables and CSS variables follow
src/scss/CLAUDE.md. - Reuse before writing. Read
src/helpers/,src/form/FormContext.tsxand the nearest component first. Anchored positioning, focus trapping, overlay stacking, scroll locking, menu and list keys, typeahead, combobox and tree state, Field wiring, announcements and locale formatting each already have a shared hook or helper. When one almost fits, extend it where it lives, with its tests, rather than copying it into the component, and put a new piece that two components would share insrc/helpers/. A new component's PR says what it reuses and what it adds.
Conventions
- Every component routes its Bulma helper props through
useBulmaClassesand forwards...rest; seesrc/helpers/CLAUDE.mdbefore adding a prop that several components share. - TSDoc is the docs source, not a comment. Every
<Foo>Propsmember needs an inline/** … */—scripts/gen-api-docs.mjsrenders those into the API page's Props table, so a missing one is a build error, and the component's own summary sentence becomes the page's Overview. The tags:@defaultValuewhen the default is computed rather than destructured (the AST can't see it),@extraProp {Type} [name=default] - descto document a notable prop inherited from the DOM base type,@helperProps <sentence>on the props type of a component that puts its helper props on another element than its other attributes (Checkbox: the outer<label>, and the<input>), which the catch-all row prints andscripts/helper-props-placement.test.mjsholds to what renders, and@flexContainer <sentence>on the props type, or a base, of a component whose root its own stylesheet makes a flex container (Stack), so the flex container helper props apply with nodisplayprop.props-extractreads it, and the ESLint plugin'sno-inert-flex-propstakes its flex containers from it through the generated metadata. Do not add@propertyblocks above an interface — that older style is unverifiable and drifted from the real types; it has been migrated away. A sub-component's own summary sentence becomes its line in the page's**Subcomponents:**list, so write it for a reader ("Top bar for navigation or branding"), not for the compiler. Type aliases get the same treatment: a union too long to inline in a cell is rendered as its name plus a**Types:**footnote built from the alias's own TSDoc. Redeclaring an inherited prop to give it TSDoc keeps the inherited type:'aria-label'?: React.AriaAttributes['aria-label'], notstring, which is narrower underexactOptionalPropertyTypesand so a breaking change.@extraPropdocuments one without redeclaring it. - Multi-part components attach sub-components as statics via
withSubComponents(src/helpers/withSubComponents.ts) — it must mutate the base (identity-preserving), never wrap it. A compound family ships these artifacts beyond the base anatomy rule: an identity test per static (expect(Parent.Sub).toBe(Sub), ortoBeDefined()+ dot-path render for module-private subs) in adescribe('Compound components')block, aCompoundUsagestory, and a### Compound (dot-notation) usagelive example at the end of the API page's## Usagesection. Prefer exporting subs by name from the same module so identity tests are possible. Compare parts throughisElementOf(src/helpers/elementType.ts), neverchild.type ===. A part written in a React Server Component reaches the client as a client reference, whose element type is lazy rather than the part's own function, so a raw comparison is false there and the parent lays the part out wrong (#1500).isElementOfreads through the lazy type, andsrc/__tests__/part-type-checks.test.tsfails on a raw comparison. A new compound that can let its parts find it through context instead, the waySegmentedControl.Segmentdoes, needs no check at all. Anything the docs say works from a Server Component needs a real Next.js build behind it, since jsdom has no server boundary. - Components must work with a custom class prefix (
ConfigProvider) — tests assertbestax--prefixed class output; never hardcode a"button"-style class string outside the classname helpers (usePrefixedClassNames). - Scope: components should map to the Bulma spec. Extras beyond Bulma (a new Carousel-like
widget) need an issue discussion first, and pair with an SCSS partial in
src/scss/when they need styles of their own. - Tests: Vitest + Testing Library on jsdom, in each folder's
__tests__/. Run one file withpnpm --filter @allxsmith/bestax-bulma exec vitest run src/elements/__tests__/Button.test.tsx.vi.spyOnon a module's export does not reach that module's own calls to it, so stub what the code reads instead (a global, a prop). Notdocumentorwindow, though: the suites run in jsdom's own context (vmForks), where those cannot be redefined, and React 18's development build readsdocumentas it handles an event. The fake timers catch jsdom's own timers too: moving focus queues a zero-delay one forselectionchange, so run it (vi.advanceTimersByTime(0)) before counting withvi.getTimerCount(). The 99% bar is reachable with the techniques insrc/components/__tests__/Reveal.test.tsx(IntersectionObserver/matchMedia mocks, SSR viarenderToStaticMarkup). A suite that compiles a whole published stylesheet compiles it withsrc/__tests__/compile-scss.ts, which says why. - Stories: types from
@storybook/react-vite;tags: ['autodocs']; every argType gets adescription(meta-test enforced). No inlinestyle={{}}in stories/docs examples — helper props; legacy inline styles exist, don't copy them. A story's picture comes fromimages/, credited inimages/LICENSE.md.check:conformance --only=image-hostsfails on a story file with a URL on a placeholder or stock-photo host. - Must pass tests on React 18 and 19 (CI matrix) — avoid single-major APIs.
- Bundle size is part of the pitch (the READMEs sell the library as tree-shakeable), so check
pnpm bundle:stats(writesdist/stats.html) when adding anything with real runtime weight. - A peer range names what somebody checked: one caret arm per major, or per minor for a 0.x
package like
material-symbols, whose minors drop glyph names. A new release gets checked against what the library uses from it and then its own arm, in afix(bulma-ui)commit, rather than a range like<1that admits releases nobody has looked at. The repo's own copies (the devDependency here and the docs site's) must sit in the newest arm, whichcheck:conformance --only=peer-rangesenforces, so the Dependabot PR that brings a release the range refuses is the one that fails (#997). create-bestax pins its icon packages to that arm as well. - A module must not do anything on import that another module relies on. The ESM build is
one file per module (
dist/esm/, behinddist/index.esm.js), and"sideEffects"lets an app's bundler skip every module it never imports, so import-time work in a skipped module silently never runs (#937). Building components, contexts and constant tables, and setting a component's owndisplayName, are fine.scripts/tree-shaking.test.mjsfails on any other call or write a built module makes as it loads, and holds a single-component import to a small slice of the library.
Releases
Independent semantic-release keyed off the bulma-ui commit scope
(release.config.js, tag @allxsmith/bestax-bulma@x.y.z). Each release also patches
bestax-mcp, so its index ships with the library (VERSIONING.md, "bestax-mcp releases with
bestax-bulma"). It publishes with
pnpm publish, like every package here (#532) — the command, its flags, and the
ways that publish fails quietly are documented in VERSIONING.md and
scripts/lib/pnpm-publish.mjs.
Two things specific to this package. It is the only scoped one, and scoped
packages default to restricted, so access has to be set somewhere or the
release is private. It is set twice over — publishConfig.access here and
--access public on the shared publish command — and either alone is enough,
so neither is load-bearing on its own. Removing both is the mistake, and it
costs more here than anywhere else. And its prepack/postpack
pair (scripts/pack-pointer-files.mjs, #344) swaps the contributor
CLAUDE.md for the consumer copy of AGENTS.md inside the tarball and puts it
back. pnpm pack --dry-run runs prepack but not postpack, and neither does
a pack that fails partway, so either leaves the consumer copy in place with a
CLAUDE.md.bak beside it. The next pack finds the swap already done and goes
on, while CLAUDE.md still matches AGENTS.md byte for byte, and its
postpack puts the contributor file back. Once either file changes, prepack
refuses and leaves both for you to sort out. To see what the tarball holds,
pnpm pack --pack-destination "$(mktemp -d)" lists its files, runs both hooks
and writes the tarball outside the repo.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

