feat(create-bestax): add controlled-Burger Navbar to the landing archetype

[allxsmith]

Pull Request

Description

Closes the landing-archetype coverage gap from the Skynet A/B prompt experiment: a model scaffolding a marketing page via bestax-layout-scaffold never saw the controlled-Burger Navbar pattern (it was only taught in the app-shell archetype), so it shipped a Navbar fixed="top" whose mobile menu could never open — a bare <Navbar.Burger /> with no active state fails silently — and offset the fixed navbar with inline padding instead of has-navbar-fixed-top.

Changes (skill source lives in repo-root skills/, synced into the package at build time):

• skills/bestax-layout-scaffold/examples/landing.tsx — the landing example now opens with a fixed-top Navbar whose Navbar.Burger/Navbar.Menu are wired to useState via active on both, plus the has-navbar-fixed-top add/remove effect on <html>, mirroring app-shell.tsx. A leading comment explains the silent-failure mode and why an inline padding offset is wrong.

• skills/bestax-layout-scaffold/references/archetypes.md §2 (Marketing / landing) — same Navbar pattern added to the skeleton, plus a Required note (controlled burger wiring, has-navbar-fixed-top, never an inline padding offset) and burger-collapse responsive behavior, matching §1's structure.

• skills/bestax-layout-scaffold/SKILL.md — the Approach bullet on fixed navbars now leads with the controlled Burger/Menu rule; a matching Checklist item was added; the landing example's description mentions the Navbar.

• create-bestax/src/constants.ts (CLAUDE_MD template) — one always-in-context House style line: Navbar.Burger/Navbar.Menu are controlled — wire active via state on both, and pair Navbar fixed="top" with has-navbar-fixed-top (never an inline padding offset).

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

• create-bestax (create-bestax)

• docs (@allxsmith/bestax-docs)

• Other (please specify): skills/ (bundled into create-bestax via sync-skills.mjs)

Related Issue(s)

Closes #348

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 (skill/template content change; no behavioral code paths added — existing 197 create-bestax tests pass)
• I have added/updated documentation as needed
• I have updated Storybook stories as needed (bulma-ui) — no skill-example story renders the landing example
• My changes require a change to the documentation
• All new and existing tests passed
• Any relevant dependencies are updated (none needed)
• If this PR changes commands, conventions, or package structure, the affected CLAUDE.md files are updated (no repo-level convention changed; the generated app CLAUDE.md template gained the Navbar line)

Screenshots / Demos

The new landing example's Navbar wiring:

const [menuOpen, setMenuOpen] = useState(false);

useEffect(() => {
  document.documentElement.classList.add('has-navbar-fixed-top');
  return () => {
    document.documentElement.classList.remove('has-navbar-fixed-top');
  };
}, []);

<Navbar fixed="top">
  <Navbar.Brand>
    <Navbar.Item href="#">Acme</Navbar.Item>
    <Navbar.Burger
      active={menuOpen}
      onClick={() => setMenuOpen(open => !open)}
      aria-label="menu"
      aria-expanded={menuOpen}
    />
  </Navbar.Brand>
  <Navbar.Menu active={menuOpen}>…</Navbar.Menu>
</Navbar>

Additional Context

• Verified: landing.tsx typechecks strict against the library's source types; prettier --check, check-conformance (incl. skills-sync), and turbo run test typecheck lint --filter=create-bestax (197 tests) all pass.
• The alternative from the issue (making Navbar.Burger auto-toggling/uncontrolled in bulma-ui) is intentionally not done here — that's a component API change for a separate bulma-ui proposal.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JDRUvpEgaMAV2UBPokA7hR

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Added guidance for controlling mobile navbar menus with shared state.
  • Documented the required has-navbar-fixed-top class for fixed-top navigation.
  • Updated landing-page examples, checklists, and archetype guidance with the corrected navbar pattern.
• Bug Fixes
  • Fixed the mobile navbar menu so it opens and closes correctly.
  • Prevented content from being hidden beneath fixed-top navigation.

[github-actions]

Preview Deployment

Preview URL: https://274524df.bestax.pages.dev

[claude]

Deep review — 0 blocking · 1 advisory

#	Severity	Area	Finding	Location
1	🔵 Advisory	Coverage	New landing wiring is validated only by tsc/prettier/conformance — no story or test renders it, so a future regression in the burger↔menu contract wouldn't be caught here	skills/bestax-layout-scaffold/examples/landing.tsx:47

Overall: The change is sound and low-risk. It closes the #348 coverage gap by adding a fixed-top Navbar with a fully controlled burger (active on both Navbar.Burger and Navbar.Menu), the has-navbar-fixed-top effect on <html>, and a leading comment naming the silent-failure mode — mirroring the already-shipped app-shell.tsx verbatim in shape. Every API usage checks out against bulma-ui/src/components/Navbar.tsx (all subcomponents and props exist), the archetypes.md §2 skeleton is structurally consistent with §1, and the one always-in-context CLAUDE_MD House-style line matches the skill guidance. The riskiest thing a human should glance at is simply whether the teaching emphasis lands — this is pedagogy-as-code, so its value is in being copied correctly by a model, not in runtime behavior.

Residual risk: the failure class is "landing scaffold ships a dead mobile burger / inline padding offset."

• Adjacent archetypes — refuted: app-shell §1 already taught this pattern (issue confirms it was correct there); the other three archetypes (centered, card-grid, content-page) have no fixed navbar, so the burger contract doesn't apply.
• Prose-only drift — refuted: the fix is reinforced at four layers (runnable example, archetype skeleton + Required note, SKILL.md Approach + Checklist, and the always-in-context CLAUDE.md line), directly addressing the issue's "prose alone didn't stick" root cause.
• Sync/catalog staleness — refuted: templates/skills/ is generated+gitignored via sync-skills.mjs, and gen-component-catalog.mjs reads API docs, not examples, so neither goes stale from this diff.

🏄 Totally chill little PR, dude — it just teaches the scaffold the same clean burger-wiring trick the app-shell already knew, so no more dead mobile menus washing up on the landing page. No gnarly waves here, cleared to paddle out.

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 53 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: 7e1c3a8e-f665-48b6-b687-2a74a126b082

📥 Commits

Reviewing files that changed from the base of the PR and between 633a6de and f3387de.

📒 Files selected for processing (3)

• skills/bestax-layout-scaffold/SKILL.md
• skills/bestax-layout-scaffold/examples/landing.tsx
• skills/bestax-layout-scaffold/references/archetypes.md

Walkthrough

The changes update navbar scaffolding guidance, landing examples, and marketing archetypes to use shared state for Navbar.Burger and Navbar.Menu, and to apply Bulma’s has-navbar-fixed-top class for fixed-top navigation.

Changes

Controlled Navbar scaffolding

Layer / File(s)	Summary
Navbar implementation guidance create-bestax/src/constants.ts, skills/bestax-layout-scaffold/SKILL.md	Scaffold instructions and checklist require shared active state for the burger and menu, plus has-navbar-fixed-top on <html>.
Controlled landing navbar skills/bestax-layout-scaffold/examples/landing.tsx	The landing example adds menu state, burger click handling, controlled menu visibility, and root-class cleanup.
Marketing archetype pattern skills/bestax-layout-scaffold/references/archetypes.md	The marketing skeleton and requirements document a fixed-top controlled navbar with responsive links and layout behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant LandingPage
  participant Navbar
  participant documentElement
  Client->>LandingPage: Clicks burger
  LandingPage->>Navbar: Passes active={menuOpen}
  LandingPage->>documentElement: Adds or removes has-navbar-fixed-top

Loading

Possibly related issues

• [Feature] create-bestax: landing archetype needs a Navbar with controlled Burger wiring (bestax-layout-scaffold) #348 — Directly covers the controlled landing Navbar pattern updated in these scaffold files.

Possibly related PRs

• allxsmith/bestax#271 — Both changes update the generated CLAUDE.md house-style scaffolding template.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding a controlled Burger Navbar pattern to the landing archetype.
Description check	✅ Passed	The description follows the template closely, covering summary, affected packages, issue link, change type, checklist, demos, and context.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/gh-issue-348-ijut2d

---

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.}

[allxsmith]

@coderabbitai review

---

Generated by Claude Code

[coderabbitai]

@allxsmith: I’ll review the changes in #355.

✅ 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: 2

🤖 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 `@skills/bestax-layout-scaffold/references/archetypes.md`:
- Around line 78-87: Update the Navbar landing archetype skeleton to define the
controlled state used by `open` and `setOpen`, or clearly label the snippet as
an excerpt requiring a parent-owned state. Ensure the documented example is not
presented as standalone code with undefined state.

In `@skills/bestax-layout-scaffold/SKILL.md`:
- Around line 48-51: The controlled-navbar guidance incorrectly says omitting
either active prop prevents the menu from opening. Update
skills/bestax-layout-scaffold/SKILL.md lines 48-51 and the matching header
comment in skills/bestax-layout-scaffold/examples/landing.tsx lines 5-7 to
explain that Navbar.Menu active controls visibility while Navbar.Burger active
synchronizes button styling and ARIA state; retain the requirement to wire both
props and the fixed-top class guidance.

🪄 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: 2d1b1443-0178-41d7-a725-39ed9f6412fd

📥 Commits

Reviewing files that changed from the base of the PR and between f711982 and 633a6de.

📒 Files selected for processing (4)

• create-bestax/src/constants.ts
• skills/bestax-layout-scaffold/SKILL.md
• skills/bestax-layout-scaffold/examples/landing.tsx
• skills/bestax-layout-scaffold/references/archetypes.md

[github-actions]

Preview Deployment

Preview URL: https://3343419f.bestax.pages.dev

[claude]

Deep review — 0 blocking · 0 advisory

#	Severity	Area	Finding	Location
—	—	—	No blocking defects found.	—

Overall: Sound and well-scoped. This is a docs/skill/template-content change that closes the landing-archetype coverage gap from #348 by teaching the controlled-Burger + has-navbar-fixed-top pattern in the one place a model scaffolding a marketing page would look. Every prop the new example and skeletons use is real against bulma-ui/src/components/Navbar.tsx — Navbar.Burger accepts active / onClick / aria-expanded (lines 220-224, and it defaults aria-expanded to !!active), Navbar.Menu accepts active, and Brand/Item/Start/End/Burger/Menu are all attached as statics (lines 569-577). landing.tsx mirrors the already-correct app-shell.tsx verbatim; the §1 skeleton also picked up the missing const [open, setOpen] declaration it had been referencing. CI is green (Build and Test, React 18 + 19, CodeQL, conformance incl. skills-sync), working tree is clean, and there is no bulma-ui/src/skill-examples/ story rendering the landing example, so nothing else needed updating.

Residual risk: The failure class (a scaffolded bare <Navbar.Burger /> or an inline padding offset) could still recur if it originated in an archetype this PR did not touch — refuted: grep for Navbar across all of bestax-layout-scaffold/examples and references shows every remaining usage (app-shell, both archetypes.md skeletons, layout-components.md) now wires active+onClick on the burger and active on the menu, with no bare burger left; and the rule was additionally lifted into always-loaded surfaces (SKILL.md Approach + Checklist, and the generated CLAUDE.md House-style block), so even non-navbar archetypes carry it. The skeletons omit an explicit aria-expanded on the burger, but the component defaults it from active, so a11y is preserved.

🏄 Pure clean sets on this one, dude — the gnarly silent-burger wipeout from #348 is patched right where the groms paddle out, every prop rides true against the real API, and CI is glassy all the way down. Send it. 🌊

[github-actions]

🎉 This PR is included in version 3.7.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 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 📦🚀