fix(create-bestax): concrete inline-style → helper-prop mapping for the never-inline rule

[allxsmith]

Pull Request

Description

The scaffolded CLAUDE.md's "never inline style={{}}" House style rule stated the prohibition and named prop families, but gave no lookup path from "the inline value I'm about to write" to "the prop I should write instead" — and the A/B experiment in #350 showed it violated 47 times in a single run, even though the model used the helper props correctly elsewhere in the same files.

This PR makes the rule followable:

• create-bestax/src/constants.ts (CLAUDE_MD template) — the House style block now carries a compact mapping table: common inline-style patterns on the left, the helper prop on the right — spacing (m*/p* with the 1–6 rem scale spelled out), textAlign, textColor/bgColor with the Bulma palette, textSize/textWeight, textTransform, display/flex props, flexGrow="1" for the flex-child height case, and visibility/responsive display* helpers.

• Explicit fallback order for values with no helper equivalent (maxWidth, one-off gradients): a named class in src/App.css passed via className — still never inline style. (Deliberately stops short of --bulma-* token guidance, per the issue's scope note.)

• Mirrored the same table into the two skills that generate the most JSX — bestax-layout-scaffold (new "Inline style → helper prop mapping" section, tightened Approach bullet and checklist) and bestax-custom-component (styling-ladder rung 1, with the no-equivalent case routed to rung 2; checklist updated) — so the mapping is in context exactly when pages are scaffolded.

• All prop names and valid values were checked against bulma-ui/src/helpers/bulmaClassHelpers.ts (spacing/text-size scales, alignments, weights, transforms, displays, visibilities).

• bulma-ui (@allxsmith/bestax-bulma)

• create-bestax (create-bestax)

• docs (@allxsmith/bestax-docs)

• Other (please specify): skills/ (bundled into create-bestax at build time)

Related Issue(s)

Closes #350

Type of Change

• Bug fix
• New feature
• Refactor
• Documentation
• Performance
• Build tooling
• Other (please describe):

Checklist

• My code follows the project style guidelines
• I have performed a self-review of my code
• I have added tests that prove my fix is effective or that my feature works (constants.test.ts asserts the mapping rows and the named-class fallback appear in the generated CLAUDE.md)
• I have added/updated documentation as needed
• I have updated Storybook stories as needed (bulma-ui)
• My changes require a change to the documentation
• All new and existing tests passed (create-bestax: 199 tests; conformance, prettier, and gen:catalog:check all green)
• Any relevant dependencies are updated
• If this PR changes commands, conventions, or package structure, the affected CLAUDE.md files are updated (no repo-level convention changed — the edited CLAUDE.md is the scaffolded template itself)

Screenshots / Demos

The new House style block in a generated app's CLAUDE.md:

| Inline style you're about to write         | Helper props instead                                      |
| ------------------------------------------ | --------------------------------------------------------- |
| `marginTop: '1rem'` (any margin/padding)   | `mt="4"` — scale: `1`=0.25rem … `6`=3rem (nearest step)   |
| `textAlign: 'center'`                      | `textAlign="centered"` (also `left`, `right`, `justified`)|
| `color: '#…'`                              | `textColor` with the nearest Bulma color                  |
| `display: 'flex'` + flex properties        | same-named props: `display="flex"`, `flexDirection`, …    |
| `height: '100%'` on a flex child           | `flexGrow="1"`                                            |

Additional Context

Skills changes were made at the repo root (skills/) per the sync rules — sync-skills.mjs re-bundles them into create-bestax at build/prepack time. ESLint enforcement of the style prop (the issue's "alternatives" section) is intentionally left as a possible follow-up hardening step.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q8Hayvdw6o35sYcxmh88ER

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Expanded styling guidance for custom components and page layouts.
  • Added a reference for translating common inline styles into available helper properties.
  • Clarified when to use named stylesheet classes for styling that has no helper equivalent.
  • Added guidance for configuring the app-wide icon library.
• Tests
  • Added coverage validating generated documentation reflects the updated styling guidance.

[github-actions]

Preview Deployment

Preview URL: https://e0c1c379.bestax.pages.dev

[coderabbitai]

Warning

Review limit reached

@allxsmith, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 26 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 45378be9-48e4-40bd-97fc-874783c324b3

📥 Commits

Reviewing files that changed from the base of the PR and between 0d993d2 and 5b58100.

📒 Files selected for processing (5)

• create-bestax/src/__tests__/constants.test.ts
• create-bestax/src/constants.ts
• scripts/check-conformance.mjs
• skills/bestax-custom-component/SKILL.md
• skills/bestax-layout-scaffold/SKILL.md

Walkthrough

Expanded inline-style guidance in generated CLAUDE.md content and two skills with helper-prop mapping tables, gap restrictions, named stylesheet fallback rules, and tests for the generated guidance.

Changes

Inline style guidance

Layer / File(s)	Summary
Generated house-style guidance create-bestax/src/constants.ts, create-bestax/src/__tests__/constants.test.ts	CLAUDE_MD now documents inline-style translations, flex spacing rules, and named-class fallbacks; tests assert the generated guidance contains these rules.
Skill styling references skills/bestax-layout-scaffold/SKILL.md, skills/bestax-custom-component/SKILL.md	Both skills now map common inline styles to helper props, prohibit helper-based gap usage, and require named stylesheet classes when no helper applies. The layout skill also documents root icon-library configuration.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• allxsmith/bestax#268: Updates custom-component guidance with related inline-style and helper-prop mapping instructions.
• allxsmith/bestax#271: Modifies the generated CLAUDE.md house-style section in the same scaffold template.
• allxsmith/bestax#343: Changes the same CLAUDE_MD template and its tests in a separate section.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding concrete inline-style to helper-prop mapping guidance.
Description check	✅ Passed	The description matches the template well, with summary, affected packages, issue, type, checklist, screenshots, and context.
Linked Issues check	✅ Passed	The changes implement #350 by adding the mapping table, mirrored skill guidance, fallback named-class behavior, and tests.
Out of Scope Changes check	✅ Passed	The touched files stay within the issue scope: constants, tests, and related skill documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/github-issue-350-y25o9z

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[claude]

Deep review — 0 blocking · 1 advisory

No.	Severity	Area	Finding	Location
1	🔵 Advisory	Correctness	"Every component accepts these" overstates the textColor/bgColor reach — Tag, Menu, Tabs, Panel, Breadcrumb do not expose those props, so on them the model would emit an inert textColor attribute. In practice the scaffolded, text-bearing components it targets (Box/Block/Title/Content/Notification/Hero) all do accept them, so the guidance lands where it is used.	skills/bestax-layout-scaffold/SKILL.md (mapping intro)

Overall: The change is sound and well-verified. This is pure prompt-guidance (CLAUDE.md template + two skills) closing issue 350 gap by adding a concrete inline-style to helper-prop table. Every factual claim I could check against the source of truth holds: the spacing scale matches Bulma 1.0.4 $spacing-values exactly (1=0.25rem to 6=3rem, so mt="4"=1rem), and textAlign/textWeight/textTransform/textSize/flexGrow/display-prop values all match bulma-ui/src/helpers/bulmaClassHelpers.ts. textColor/bgColor — which at first glance looked wrong versus the raw color/backgroundColor helpers — are in fact the correct remapped props on the 43 high-level components scaffolding composes (Box omits color/backgroundColor and re-adds textColor/bgColor). The src/App.css fallback target exists in the Vite react-ts scaffold, skills are re-bundled at build/prepack (no stale committed copy), and all 199 create-bestax tests pass. The human should focus on whether textColor/bgColor is the right universal recommendation given the handful of components that only take color.

Residual risk:

• Wrong prop name in guidance elsewhere: refuted — I cross-checked every prop name and value token in all three copies of the table against bulmaClassHelpers.ts and Bulma spacing.scss; the only imperfect mapping is the textColor/bgColor universality caveat above (advisory).
• Broken fallback file reference: refuted — src/App.css ships in the Vite react-ts template the scaffolder builds on.
• Stale bundled skill copy shipping old text: refuted — create-bestax/package.json runs sync-skills.mjs on both build and prepack, and there is no committed create-bestax/skills copy to drift.

🏄 Pure vibes on this one, dude — no new code to crash, just a cleaner map from gnarly inline style to the chill helper prop. Numbers all check out against the source, tests are green, so paddle it out. Only ripple is calling the color props "every component" when a couple of the little dudes do not take em — totally mergeable.

[github-actions]

Preview Deployment

Preview URL: https://659cdb83.bestax.pages.dev

[allxsmith]

@coderabbitai review

---

Generated by Claude Code

[coderabbitai]

@allxsmith I’ll review the changes in #357.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

@allxsmith I’ll review the changes in #357.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@create-bestax/src/__tests__/constants.test.ts`:
- Around line 237-257: Extend the tests in the inline-style documentation
assertions to cover the complete fallback contract: in the no-helper test,
assert that unsupported values use a named class via className, and add
assertions protecting the documented Grid/Columns gap exception. Keep the
existing src/App.css and no-inline-style assertions unchanged.

In `@skills/bestax-layout-scaffold/SKILL.md`:
- Around line 62-86: Replace the detailed inline-style helper mapping in
skills/bestax-layout-scaffold/SKILL.md lines 62-86 with a concise summary and
link to a references/ document containing the complete guidance. Apply the same
replacement in skills/bestax-custom-component/SKILL.md lines 105-126, ensuring
both skills link to the shared detailed mapping and retain only essential
always-loaded guidance.
- Around line 62-86: Update the layout helper guidance in
skills/bestax-layout-scaffold/SKILL.md (lines 62-86) to state that ordinary flex
layouts lack a gap helper, while Grid and Columns support gap. Narrow the no-gap
rule in skills/bestax-custom-component/SKILL.md (lines 103-106) so it applies
only to flex layouts, preserving the existing guidance for Grid and Columns.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 011e3929-d27f-4b15-ad31-821f7ff5af8f

📥 Commits

Reviewing files that changed from the base of the PR and between f711982 and 0d993d2.

📒 Files selected for processing (4)

• create-bestax/src/__tests__/constants.test.ts
• create-bestax/src/constants.ts
• skills/bestax-custom-component/SKILL.md
• skills/bestax-layout-scaffold/SKILL.md

[github-actions]

Preview Deployment

Preview URL: https://a5bf8c6f.bestax.pages.dev

[github-actions]

Preview Deployment

Preview URL: https://92c37998.bestax.pages.dev

[claude]

Deep review — 0 blocking · 1 advisory

#	Severity	Area	Finding	Location
1	🔵 Advisory	Robustness	The mapping table now exists in three copies (constants.ts + both skills) but only the constants.ts copy is test-guarded — the skill copies can silently drift from the helper source.	skills/bestax-*/SKILL.md

Overall: The change is sound. It is a documentation/template-only PR that turns the "never inline style={{}}" prohibition into a concrete inline-style → helper-prop lookup table, exactly as issue #350 requested. I verified every factual claim in the table against bulma-ui/src/helpers/bulmaClassHelpers.ts and the component sources: the spacing scale (1=0.25rem … 6=3rem, Bulma's default $spacing-values), textAlign alignments, the textColor/bgColor palette, textSize 1–7 (1 largest), textWeight, textTransform, the flex prop names, flexGrow (valid 0–5), visibility="hidden" (→ is-hidden → display:none), and displayMobile/displayTablet all match. The content-vs-semantic-color nuance is correct too: textColor/bgColor live on content components (Box in elements/, Card, etc.) while Tag/Tabs/Panel take color. SubTitle exists. The 35 constants.test.ts cases pass. The riskiest part is just long-term drift of the triplicated table (advisory #1) — the human should confirm they're comfortable maintaining three copies rather than a single sourced constant.

Residual risk:

• Table factual accuracy — refuted: cross-checked each row's prop name and value set against bulmaClassHelpers.ts (validSizes, validTextSizes, validAlignments, validTextWeights, validTextTransforms, validFlexGrowShrink, validVisibilities, BulmaDisplayProps) and the component prop declarations; all consistent.
• Skill-vs-template divergence — real but low: the constants.ts copy is asserted by tests; the two SKILL.md copies are not, and the bestax-layout-scaffold copy already carries an extra gap: row the others lack. Not a defect today (all rows are correct), just a maintenance seam recorded above.
• Sync mechanism — not exercised here: skills are re-bundled into create-bestax by sync-skills.mjs at build/prepack, outside this diff; nothing in the PR changes that path.

🏄 Pure cruise, dude — no code waves to wipe out on, just a clean map from style={{}} to the right helper prop, and every value checks out against the source. Send it.

[Copilot]

Pull request overview

This PR updates the create-bestax scaffold guidance and the two most JSX-heavy skills to make the “never inline style={{}}” house rule actionable by adding a concrete inline-style → helper-prop mapping (plus an explicit fallback when no helper exists). It also adds automated safeguards (Jest + conformance) to keep the three intentionally duplicated copies in sync.

Changes:

• Added a compact mapping table (inline style patterns → helper props) and a named-class fallback rule to the scaffolded CLAUDE.md template.
• Mirrored the same mapping into bestax-layout-scaffold and bestax-custom-component so it’s present at generation time.
• Added a conformance gate to ensure the three mapping copies stay synchronized, and added Jest assertions for the template output.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
skills/bestax-layout-scaffold/SKILL.md	Adds an “Inline style → helper prop mapping” section and updates the checklist/rules to reference it.
skills/bestax-custom-component/SKILL.md	Extends the “Styling ladder” rung-1 guidance with the mapping table and a clear no-helper fallback.
scripts/check-conformance.mjs	Adds style-mapping-sync conformance check to keep the triplicated mapping consistent.
create-bestax/src/constants.ts	Updates the scaffolded CLAUDE_MD house-style block with the mapping table and fallback order.
create-bestax/src/tests/constants.test.ts	Adds tests asserting the generated CLAUDE.md includes the mapping, fallback, and gap guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

Preview Deployment

Preview URL: https://1805e425.bestax.pages.dev

[allxsmith]

@coderabbitai review

---

Generated by Claude Code

[coderabbitai]

@allxsmith I’ll review the changes in #357.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[github-actions]

Preview Deployment

Preview URL: https://a8d8c8f4.bestax.pages.dev

[github-actions]

🎉 This PR is included in version 3.7.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 5.8.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀