bestax
CLAUDE.md14 starsChanged 8 days agoMITView on GitHub
Docusaurus 3. Dev server: pnpm docs (from repo root) → http://localhost:3000. Production build: pnpm exec turbo run build --filter=@allxsmith/bestax-docs (builds bulma-ui first). Deploys to Cloudflare Pages from docs/build/ via .github/workflows/deploy.yml. - docs/api/ — API reference, one page per component, in folders mirroring bulma-ui/src/ (elements/, components/, form/, layout/, columns/, grid/, helpers/). A new component gets its page here — it's step 4 of the anatomy rule in bulma-ui/CLAUDE.md. - docs/guides/ — task-oriented guides (getting-started/, features/, library/, helpers/, llms/). - docs/components/, blog/,…
- Installs packages
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
- bulma-ui/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- create-bestax/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
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 77
Every category except helpers/ is managed.
- Very specific: line 83
No inline style={{}} in examples — use Block/helper props.
- Very specific: line 166
Guides are canonical reference, not lab notebooks: No run statistics, run ids, dated observations or "as of" tallies in docs/docs/: the LLM …
≈ “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
docs — the Docusaurus site (bestax.io)
Docusaurus 3. Dev server: pnpm docs (from repo root) → http://localhost:3000.
Production build: pnpm exec turbo run build --filter=@allxsmith/bestax-docs (builds bulma-ui
first). Deploys to Cloudflare Pages from docs/build/ via .github/workflows/deploy.yml.
Layout
docs/api/— API reference, one page per component, in folders mirroringbulma-ui/src/(elements/,components/,form/,layout/,columns/,grid/,helpers/). A new component gets its page here — it's step 4 of the anatomy rule inbulma-ui/CLAUDE.md.docs/guides/— task-oriented guides (getting-started/,features/,library/,helpers/,llms/).docs/components/,blog/,src/— Docusaurus scaffolding, landing page, posts.sidebars.js— navigation; new pages must be reachable from it (or via autogenerated dirs).plugins/devto-preprocessor.js— local plugin; blog posts are syndicated, keep frontmatter compatible.
The LLM docs pipeline (this site is machine-read)
The build runs docusaurus-plugin-llms (configured in docusaurus.config.js), regenerating:
/llms.txt(curated index) and/llms-full.txt(full concatenation)- a per-page
.mdtwin for every doc page (sollms.txtlinks resolve)
The plugin reads source markdown, and since 0.5.0 it strips PascalCase JSX tags while keeping their inner text. That single rule decides how components must be authored if their content is to reach an agent:
- Content in children survives. A fenced code block wrapped in a component comes out the
other side as exactly that fence, wrapper gone. This is why
<PackageManagerTabs>takes a pnpm fence as its children rather than acommandprop — the artifact is then correct by construction, with no build step to keep in sync. - Content in props does not. It goes with the tag, silently. A self-closing
<PackageManagerTabs command="…" />left an empty section in every artifact while the rendered site looked fine. Before giving a docs component a prop that carries prose or a command, check what the generated.mdlooks like.
Docusaurus's <TabItem label="…"> is handled by the plugin itself: it writes the label as a
bold line ahead of the tab's body, so a <Tabs> block keeps which option is which.
The plugin also drops HTML comments outside code, and with them the <!-- bestax:generated -->
markers, a source-control device no reader of the site needs. The rule: the keyword
bestax:generated must never reach the built markdown or the llms files, so a docs page or blog
post that wants to show marker syntax shows it without the keyword. build chains
scripts/check-generated-markers.mjs to check that, and that script's header says exactly what
the step checks and fails on.
Consequences: moving/renaming/deleting a doc page changes the published LLM index that AI
agents consume — treat URL changes like API changes. The canonical AI entrypoint is the LLMs
guide (docs/guides/llms/ → https://bestax.io/docs/guides/llms) — don't add new competing
entrypoints. (Converging every discovery surface on that URL was evaluated and declined in
#203: discovery already resolves in 1–2 hops from every entrypoint and no peer library does
it, so a novel non-standard package.json key and extra release churn weren't worth it.)
Conventions
- API pages mirror
docs/api/components/avatar.md(the house exemplar), not older siblings;check:conformanceenforces the required sections. Frontmattertitle:= the exported name, and the first## Overviewsentence becomes its catalog one-liner (gen:catalog). - Parts of an API page are generated (
pnpm gen,scripts/gen-api-docs.mjs). Regions delimited by<!-- bestax:generated <id> -->/<!-- /bestax:generated <id> -->are machine-owned and hand-edits are reverted:overview(the summary sentence, from the component's TSDoc),import,props(from the<X>Propsinterfaces) andcssvars(parsed from the SCSS). To change a props table, change the TSDoc on the interface member. Prose outside the markers — including admonitions right below the Overview sentence — is yours. Deleting a marker pair opts that region out;docs-section-ordermakes that visible rather than silent. One exception to that opt-out:cssvarspresence is data-driven — the section renders only when the component'sSCSS_SOURCESentry (inscripts/lib/api-sources.mjs) is non-empty, so a wrong[]there suppresses it with every gate green (#464; the orphan rule incheck:conformancenow catches the unclaimed-partial half of that). Managed categories are listed inscripts/lib/api-sources.mjs— the set starts empty and grows one category per PR, so a page is only generated once its category lands. - Section order on a managed page: Overview, Import, Usage, (page-specific extras),
Accessibility, Related Components, Additional Resources, Props, CSS & Sass Variables.
Every category except
helpers/is managed; the hook pages there have no## Propsat all, andconfig.md/theme.mdfollow the order but keep their hand-written tables. - The
propsregion owns the tables and nothing else. Prose inside## Propsis preserved above the opening marker or below the closing one — but prose sitting between two tables has nowhere to go, so move it out first. A###heading that is not one of the component's sub-components (### TaginputTag) ends the region rather than being swallowed by it. - No inline
style={{}}in examples — useBlock/helper props. - An example's picture is one the site serves from
static/img.check:conformance --only=image-hostsfails on a docs page, or a file undersrc/, with a URL on a placeholder or stock-photo host. - 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).
jsxandtsxfences are linted with the ESLint plugin'srecommendedrules, inpnpm test(scripts/eslint-plugin-docs.test.mjs, whose header says how a fence is read). That catches a helper value the library drops without a word (textAlign="center"), a deprecated prop, and a flex prop that emits nothing. A fence needs no import for it. A fence that is wrong on purpose, such as a rule's ✗ example, takesnolintin its info string (```jsx nolint), which changes nothing on the rendered page. The marker is per fence so the rest of the page is still checked, and it fails once nothing in the fence is reported, so it goes when the mistake does. A fence the test cannot parse fails too, marked or not, since no rule can read it. An example that is not code at all belongs in atextfence. Ajsx liveortsx livefence is also type-checked against the library's build, inpnpm test(scripts/docs-fence-types.test.mjs, whose header says how a live fence is read), so a prop the component does not take fails even though the page renders. One that is wrong on purpose takesnotypecheckin its info string (```tsx live notypecheck), which also changes nothing on the page. It holds only while the fence still has a type error, so it goes when the mistake does, the waynolintdoes.- Live examples render in a shadow root, and the preview
(
src/theme/CodeBlock/ShadowLivePreview.js) wraps each one in aConfigProviderwhoseportalContaineris an element inside that root, so what an example portals keeps the preview's styles. AConfigProviderthe example nests replaces that setting rather than adding to it, and its portaled content lands unstyled indocument.bodywith every gate green. In an example that portals, don't nest one, or give it aportalContainer: an element the example renders, or the preview's own, read withuseConfig(). Every preview loadsbestax.css, and an example's import lines are dropped. An example that imports the prefixed build gets that stylesheet in its own preview as well, afterbestax.css.FENCE_STYLESHEETSinsrc/components/ShadowPreview/shadowStyles.jslists the builds that load this way, and says which builds can. - A live example opens in StackBlitz and CodeSandbox from the two buttons beside its copy
button (
src/theme/CodeBlock/SandboxButtons, builders insrc/theme/CodeBlock/sandbox/). The project is built in the reader's browser when they click, from the code in the editor: the fence becomes anApp.tsxwith exactly the imports it uses, its/img/...paths in strings and CSSurl()s pointed at the site since a sandbox has nostatic/img, inside the create-bestaxvite-tstemplate (StackBlitz; CodeSandbox gets a Create React App layout), installing the library release this build read or a later compatible one. An example that imports a prefixed build opens with the library stylesheets it imports in place of the template'sbestax.css(librarySheetsIninsandbox/projects.mjs, which says how that differs from the page's preview). Nothing is published ahead of time and a fence needs no marker. A component that exists only in this site goes inDOCS_ONLY_NAMESinsrc/theme/CodeBlock/sandbox/scope-names.mjsand gets its value in thepickcall insrc/theme/CodeBlock/scope.js: an example using one shows no sandbox buttons, since no sandbox can install it. Export it fromsrc/components/SkillExamples, where scope.js imports it: the corpus gate (scripts/docs-fence-types.test.mjs) binds every name on that list from there in itsasModuleheader, and fails on one it cannot find. That test also runs the converter over every live fence that is not markednotypecheck, and type-checks what it writes, so a fence it cannot convert failspnpm testinstead of opening broken; a failure there is the converter's to fix, not the fence's. The tests stop at the files a sandbox is built from, so open one plain example and one example with icons in each service before merging a bump of@stackblitz/sdkor react-live, and again once a bulma-ui release that changes its exports, dependencies or CSS file names is on npm, which is where a sandbox installs it from. Install and run commands go in
<PackageManagerTabs>, wrapping the pnpm fence you would have written anyway, so npm/yarn/bun readers don't translate by hand:<PackageManagerTabs> ```bash pnpm create bestax@latest my-app cd my-app pnpm install ``` </PackageManagerTabs>Registered globally in
src/theme/MDXComponents.js— no import. Write the pnpm form exactly, one command per line; npm, yarn and bun are derived from it, and a line that isn't a pnpm verb (cd my-app, a#comment) passes through unchanged. Blank lines around the fence are required — without them MDX treats it as literal text, not a code block. The component derives the command back out of the fence and throws during the prerender if the round trip isn't exact, so a non-canonical fence (npm install foo, odd spacing) fails the build rather than rendering tabs derived from something the page never showed. Docs-tree pages only — a syndicated blog post must not use it (JSX reaches dev.to as raw text); see the Syndication section ofblog/CLAUDE.md..mdfiles here render JSX, becausemarkdown.formatdefaults tomdxanddocusaurus.config.jsdoes not override it. That is load-bearing but easy to miss: settingformat: 'detect'would make every.mdpage render its tags as literal text.- Markdown is prettier-formatted (
pnpm format:checkcoversmd/mdx). - Guides are canonical reference, not lab notebooks. No run statistics, run ids, dated
observations or "as of" tallies in
docs/docs/**: the LLM index serves it as current fact, and a count is stale the day after it is written. Dated snapshots belong inblog/, which is excluded from the index (seeblog/CLAUDE.md). Evidence goes on the issue or PR and the guide links it. A claim that needs a number to be true belongs in a test or a generator, not a sentence. A guide section says what the operator can do and what each switch is compared against; it does not re-derive a third party's internals. Claim the case in front of you: "every" and "only" are one counterexample from false. Never cite a line number; cite a heading, a step id, or a flag.check:conformance --only=fragile-proseenforces the count, run-id, and line-reference parts overdocs/docs/guides/**; the migration guides are exempt because their counts describe a frozen upstream, and the API pages are generated. The rule still holds everywhere indocs/docs/**— the check is a net, not the contract. The library comparison page is the one guide that shows dated data, and only through its component, which the index strips; its prose follows this rule (see "The State of React" inblog/CLAUDE.md). - The Templates page (
/templates,src/pages/templates/, modeled on the Docusaurus showcase) lists the Bulma templates ported intotemplates/at the repo root, whose porting guide istemplates/CLAUDE.md. Its data issrc/data/templates.js, plain data with no imports, and the file's header documents each field and the tags. Each card's screenshot isstatic/img/templates/<slug>.jpg, written bypnpm --filter @allxsmith/bestax-docs screenshot:template <slug>, which builds the template from a copy of the files git tracks in its folder and captures the preview: our capture of the port, never the upstream's image, and a manual step that CI does not run.scripts/templates.test.mjsat the repo root holds every entry to its folder and its screenshot and back, so a template, its entry and its screenshot land in one PR. A card opens StackBlitz through a plain anchor rather than the SDK the live examples use, so it works without JavaScript, and it never links the upstream's live site. It opens the template from the allxsmith/bestax-templates mirror, named once in the data file; CONTRIBUTING.md ("The bestax-templates repository") covers the mirror. The filters live in the URL throughuseQueryStringanduseQueryStringListfrom@docusaurus/theme-common, and the page reuses ComponentComparison's stylesheet for its chips, search box and panels rather than keeping a copy. - Scripts in
docs/scripts/are covered by the rootpnpm lint— run it before pushing even a docs-only PR (#471 broke CI on exactly this). Playwrightpage.evaluatecallbacks execute in the browser, so declare the browser globals each callback actually uses (/* global document */in bulma-ui'scapture-stories.mjs;/* global document, getComputedStyle */inrasterize-cover.mjs) — and when a script already has the page open, validate through the parsed DOM and computed styles, not regexes over the source (quoting,data-*attributes, and transparent paint all fool regexes; two review rounds proved it).
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.

