agentleFS
allxsmithallxsmith/bestax/bulma-ui/CLAUDE.md

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…

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
  1. Very specific:

    If the change invalidates guidance in skills/, update the skill in the same PR.

    line 30
  2. Very specific:

    Reuse before writing: Read src/helpers/, src/form/FormContext.tsx and the nearest component first.

    line 127
  3. Very specific:

    Every component routes its Bulma helper props through useBulmaClasses and forwards ...rest.

    line 136
  4. Very specific:

    TSDoc is the docs source, not a comment: Every <Foo>Props member needs an inline / … */ — scripts/gen-api-docs.mjs renders those into the …

    line 138
  5. Distinctive:

    Must pass tests on React 18 and 19 (CI matrix) — avoid single-major APIs.

    line 200

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 model
  • src/layout/ — page structure (Container, Section, Hero, …)
  • src/columns/ — flexbox column system; src/grid/ — CSS Grid system
  • src/helpers/ — the shared helper-prop system (useBulmaClasses), Theme, Config
  • src/scss/ — SCSS for the "extras" (components beyond stock Bulma) + flavor builds
  • src/skill-examples/ — Storybook stories showcasing agent-generated output of the skills/
  • 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 -->

  1. src/<folder>/Foo.tsx — the component
  2. src/<folder>/__tests__/Foo.test.tsx — tests (coverage threshold: 99%, vitest.config.ts)
  3. src/<folder>/Foo.stories.tsx — Storybook story
  4. docs/docs/api/<folder>/foo.md — the API docs page
  5. src/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's external, so a future useMemo in 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.cts rule below depends on.
  • The CommonJS artifact must be constants.cjs, not constants.cjs.js. This package is "type": "module", so Node reads a .js file as ESM whatever the bundle's format is, and a bundle writing exports.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 .cjs does not depend on which one appears.
  • The emitted declarations need .js on every relative specifier, added by a build step. tsc writes them exactly as the source spells them, and this package is "type": "module", so TypeScript reads a .d.ts as ESM where an extensionless specifier does not resolve — every re-export failed and the root had no usable types at all (#696). Marking dist/types CommonJS 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 from closeBundle at 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 the require one must be constants.d.cts. The same rule, one layer up and less visible: a .d.ts in a "type": "module" package is read as ESM by TypeScript, so a module: node16 CommonJS 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.cts is written by a rollup hook as a VERBATIM COPY of the declaration, not as a re-export of it, because a .d.cts re-exporting from a .d.ts hits 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 and scripts/constants-subpath.test.mjs both 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, defaultOpen and onOpenChange(open) (Popover, Collapse, Command, Combobox, HoverCard). A selected index or value is value, defaultValue and onChange(value) (Tabs, Combobox), not index or activeIndex; Carousel and Steps name their position value too. Any other controlled state is x, defaultX and onXChange (TreeView's selected and expanded). Modal's active and Dialog's and Sidebar's isOpen came 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: isRounded for is-rounded, hasAddons for has-addons. A behaviour switch takes the native attribute's name or the one a sibling already uses (disabled, closeOnEscape, Sidebar's overlay).
  • A container that lays out several standalone components takes their name in the plural: Buttons, Tags, Avatars, Collapses, Checkboxes, Radios. A .Group part 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 Group is the row of that family, neither a plural nor a .Group part, and the rule above doesn't rename it.
  • color takes Bulma's color names and size the '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 reads LocaleProvider.
  • Class names, Sass variables and CSS variables follow src/scss/CLAUDE.md.
  • Reuse before writing. Read src/helpers/, src/form/FormContext.tsx and 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 in src/helpers/. A new component's PR says what it reuses and what it adds.

Conventions

  • Every component routes its Bulma helper props through useBulmaClasses and forwards ...rest; see src/helpers/CLAUDE.md before adding a prop that several components share.
  • TSDoc is the docs source, not a comment. Every <Foo>Props member needs an inline /** … */ — scripts/gen-api-docs.mjs renders 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: @defaultValue when the default is computed rather than destructured (the AST can't see it), @extraProp {Type} [name=default] - desc to 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 and scripts/helper-props-placement.test.mjs holds 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 no display prop. props-extract reads it, and the ESLint plugin's no-inert-flex-props takes its flex containers from it through the generated metadata. Do not add @property blocks 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'], not string, which is narrower under exactOptionalPropertyTypes and so a breaking change. @extraProp documents 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), or toBeDefined() + dot-path render for module-private subs) in a describe('Compound components') block, a CompoundUsage story, and a ### Compound (dot-notation) usage live example at the end of the API page's ## Usage section. Prefer exporting subs by name from the same module so identity tests are possible. Compare parts through isElementOf (src/helpers/elementType.ts), never child.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). isElementOf reads through the lazy type, and src/__tests__/part-type-checks.test.ts fails on a raw comparison. A new compound that can let its parts find it through context instead, the way SegmentedControl.Segment does, 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 assert bestax--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 with pnpm --filter @allxsmith/bestax-bulma exec vitest run src/elements/__tests__/Button.test.tsx. vi.spyOn on 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). Not document or window, though: the suites run in jsdom's own context (vmForks), where those cannot be redefined, and React 18's development build reads document as it handles an event. The fake timers catch jsdom's own timers too: moving focus queues a zero-delay one for selectionchange, so run it (vi.advanceTimersByTime(0)) before counting with vi.getTimerCount(). The 99% bar is reachable with the techniques in src/components/__tests__/Reveal.test.tsx (IntersectionObserver/matchMedia mocks, SSR via renderToStaticMarkup). A suite that compiles a whole published stylesheet compiles it with src/__tests__/compile-scss.ts, which says why.
  • 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; legacy inline styles exist, don't copy them. A story's picture comes from images/, credited in images/LICENSE.md. check:conformance --only=image-hosts fails 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 (writes dist/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 a fix(bulma-ui) commit, rather than a range like <1 that 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, which check:conformance --only=peer-ranges enforces, 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/, behind dist/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 own displayName, are fine. scripts/tree-shaking.test.mjs fails 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.