fix(create-bestax): dark-mode contrast rules in theming/layout skills and docs

[allxsmith]

Pull Request

Description

One combined "Contrast & dark mode" pass covering both #194 and #195 (the issues themselves suggest merging them — same root cause: scheme flips interacting with fixed-color surfaces).

• bulma-ui (@allxsmith/bestax-bulma)
• create-bestax (create-bestax) — ships the updated skills
• docs (@allxsmith/bestax-docs)
• Other: skills/bestax-theming, skills/bestax-layout-scaffold

#194 (silent single-mode contrast failure):

• bestax-theming/SKILL.md gains a "Contrast rules (dark mode is on by default)" section: pin colorMode for single-mode designs; derive custom tokens from scheme vars (or provide the [data-theme='dark'] pair) for dual-mode; fixed-color surfaces pin their content colors.
• references/css-variables.md gains "The single-mode contrast trap" with the full failure explanation (OS dark mode flips --bulma-text while author-defined fixed tokens stay light → white text on cream, invisible unless the author's own OS is dark) and both copy-pasteable remedies.
• Docs: new "Dark Mode & Contrast" section in the CSS variables guide; a warning admonition on the Theme API page's Dark Mode section links to it.

#195 (washed-out outlined CTAs on a dark hero):

• bestax-layout-scaffold/SKILL.md Approach gains the hero-CTA rule: filled buttons only on a colored hero (color="light", or color="primary" isInverted — solid white with primary text); never a thin isOutlined secondary. The landing archetype in references/archetypes.md repeats it where the skeleton lives.
• examples/landing.tsx drops isOutlined from its secondary CTA — this was the exact pattern the issue reported agents copying (color="primary" isInverted isOutlined), fixed per the skills rule "fix the guidance that produced the bad output, not just the example" (both are fixed here).

Deviations from the issue text, for the record:

• Both issues also name a frontend-design skill — no such skill exists in this repo (verified by search), so its share of the guidance lives in the theming and layout skills, which are the surfaces agents actually load here.
• [Docs] Warn that custom light-palette tokens break contrast under OS dark mode; document the "lock the scheme or theme both modes" rule #194's suggested before/after screenshot is omitted — the guide section explains the failure textually; happy to add screenshots in a follow-up if wanted.

Related Issue(s)

Closes #194
Closes #195

Type of Change

• Bug fix (shipped-skill guidance)
• Documentation

Checklist

• My code follows the project style guidelines
• I have performed a self-review of my code
• I have added/updated documentation as needed
• All new and existing tests passed (no package code changed; prettier + format:check green; full docs build green including the new cross-page anchor)
• If this PR changes commands, conventions, or package structure, the affected CLAUDE.md files are updated (none affected)

Additional Context

Scoped fix(create-bestax) because the skills are shipped inside create-bestax and this corrects guidance that produces broken output — it should cut a patch release.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Pohc8xLkdx4gwXkW3xd7up

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Expanded dark mode guidance with Bulma warnings about OS-based theme detection when colorMode isn’t set.
  • Added “Dark Mode & Contrast” and “single-mode contrast trap” sections with rules to avoid scheme inversion and maintain readability (including guidance for fixed-color surfaces and paired content).
  • Updated theming and hero CTA styling recommendations across guides and references.
• Style
  • Updated the landing-page hero primary CTA to use a solid inverted button (instead of an outlined style) to improve dark-mode contrast.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ba3bae74-97e2-4c16-85ce-ad21c851304e

📥 Commits

Reviewing files that changed from the base of the PR and between b22840a and 82aea1b.

📒 Files selected for processing (3)

• docs/docs/guides/features/css-variables.md
• skills/bestax-theming/SKILL.md
• skills/bestax-theming/references/css-variables.md

🚧 Files skipped from review as they are similar to previous changes (2)

• skills/bestax-theming/SKILL.md
• skills/bestax-theming/references/css-variables.md

---

Walkthrough

Changes

The PR adds dark-mode contrast guidance to API, CSS-variable, and theming documentation, including scheme pinning and custom-token rules. It also updates hero CTA guidance and changes the landing example’s Live demo button from outlined to solid inverted styling.

Contrast and dark-mode guidance

Layer / File(s)	Summary
Dark-mode behavior and token rules docs/docs/api/helpers/theme.md, docs/docs/guides/features/css-variables.md, skills/bestax-theming/SKILL.md, skills/bestax-theming/references/css-variables.md	Documents OS-driven scheme changes, single-mode theme pinning, scheme-derived custom tokens, and fixed-surface content rules.
Hero CTA contrast guidance skills/bestax-layout-scaffold/SKILL.md, skills/bestax-layout-scaffold/references/archetypes.md, skills/bestax-layout-scaffold/examples/landing.tsx	Specifies filled CTA variants for colored hero surfaces, recommends pinning the root theme for single-mode designs, and updates the Live demo button to solid inverted styling with a contrast explanation comment.

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

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the docs and skill guidance updates for dark-mode contrast in create-bestax.
Description check	✅ Passed	The description follows the template with affected packages, related issues, change type, checklist, and context.
Linked Issues check	✅ Passed	The changes cover the documented contrast trap and hero CTA guidance, including the landing example and shipped skills.
Out of Scope Changes check	✅ Passed	The diff stays within the requested docs, skills, and example updates for dark-mode contrast guidance.
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 docs/194-195-contrast

---

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

[github-actions]

Preview Deployment

Preview URL: https://4f7d6100.bestax.pages.dev

[claude]

Deep review — 0 findings

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

Overall: This is a docs- and skills-only change fixing the dark-mode contrast footguns from #194/#195, and the guidance is technically sound. I verified the load-bearing claims: Bulma v1 really does apply its dark scheme via prefers-color-scheme when no data-theme is set (so "dark mode on by default" is accurate); color="primary" isInverted renders a white surface with primary text as the landing example comment describes; and the new cross-doc anchor ../../guides/features/css-variables.md#dark-mode--contrast resolves both the path and the github-slugger slug (& dropped, leaving the double dash) correctly. The landing example's isOutlined removal is valid and no mirrored showcase in bulma-ui/src/skill-examples/ references that hero, so nothing else in the same-PR skill contract is left stale. Riskiest surface is simply whether the prose rules match real Bulma behavior — they do — so a human can focus on tone/wording rather than correctness.

🏄 Pure knowledge-drop, no code to wipe out on — the contrast rules ride true, the anchors stick the landing, and every claim holds against the actual Bulma wax. Clean set, ship it.

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@docs/docs/api/helpers/theme.md`:
- Around line 411-415: Clarify the omitted colorMode behavior consistently: an
existing data-theme is preserved, and OS-driven color mode is used only when no
explicit theme attribute is present. Update the warning in
docs/docs/api/helpers/theme.md lines 411-415, the opening claim in
docs/docs/guides/features/css-variables.md lines 325-328, the guidance in
skills/bestax-theming/SKILL.md lines 40-44, and the conflicting text in
skills/bestax-theming/references/css-variables.md lines 152-154, preserving the
intended light/dark contrast recommendations.

🪄 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: 5fb6dd42-a5f3-49b0-917c-a7ac8a822f99

📥 Commits

Reviewing files that changed from the base of the PR and between 245f0d2 and a995241.

📒 Files selected for processing (7)

• docs/docs/api/helpers/theme.md
• docs/docs/guides/features/css-variables.md
• skills/bestax-layout-scaffold/SKILL.md
• skills/bestax-layout-scaffold/examples/landing.tsx
• skills/bestax-layout-scaffold/references/archetypes.md
• skills/bestax-theming/SKILL.md
• skills/bestax-theming/references/css-variables.md

[github-actions]

Preview Deployment

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/docs/guides/features/css-variables.md (1)

346-360: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Handle OS-driven dark mode in the custom-token example.

The [data-theme='dark'] override is insufficient when colorMode="system" (or an omitted colorMode) leaves <html> without data-theme; Bulma then follows prefers-color-scheme, but these custom tokens remain light. Add a @media (prefers-color-scheme: dark) override scoped to :root:not([data-theme]), or explicitly require setting data-theme for this approach.

As per path instructions, this documentation must accurately document the library API; the Theme API contract states that colorMode="system" removes data-theme and delegates scheme selection to the OS.

Proposed documentation fix

-/* Or keep custom values, but flip them too: */
+/* Or keep custom values, but flip them for explicit and OS-driven dark mode: */
 [data-theme='dark'] {
   --my-canvas: `#14251b`;
   --my-ink: `#eef3e7`;
 }
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) {
+    --my-canvas: `#14251b`;
+    --my-ink: `#eef3e7`;
+  }
+}

🤖 Prompt for 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.

In `@docs/docs/guides/features/css-variables.md` around lines 346 - 360, Update
the custom-token example in the Rule 2 section to cover system/omitted
colorMode, adding a prefers-color-scheme: dark override scoped to
:root:not([data-theme]) with the dark token values. Preserve the existing
explicit [data-theme='dark'] override so explicit theme selection continues to
work.

Source: Path instructions

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

Outside diff comments:
In `@docs/docs/guides/features/css-variables.md`:
- Around line 346-360: Update the custom-token example in the Rule 2 section to
cover system/omitted colorMode, adding a prefers-color-scheme: dark override
scoped to :root:not([data-theme]) with the dark token values. Preserve the
existing explicit [data-theme='dark'] override so explicit theme selection
continues to work.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d8291aa7-230b-4715-8589-1e81f9fe9d40

📥 Commits

Reviewing files that changed from the base of the PR and between a995241 and b22840a.

📒 Files selected for processing (4)

• docs/docs/api/helpers/theme.md
• docs/docs/guides/features/css-variables.md
• skills/bestax-theming/SKILL.md
• skills/bestax-theming/references/css-variables.md

🚧 Files skipped from review as they are similar to previous changes (3)

• docs/docs/api/helpers/theme.md
• skills/bestax-theming/SKILL.md
• skills/bestax-theming/references/css-variables.md

[allxsmith]

CodeRabbit's outside-diff Major is confirmed and fixed in 82aea1b: the [data-theme='dark'] override alone never fires under colorMode="system"/unset (no attribute → Bulma flips via prefers-color-scheme while the custom tokens stay light — the very trap this PR documents). Both keep-custom-values examples (guide + skill reference) now pair it with @media (prefers-color-scheme: dark) { :root:not([data-theme]) { … } }, the SKILL.md rule names both paths, and the text now notes this is exactly why scheme-derived tokens are the preferred form.

---

Generated by Claude Code

[github-actions]

Preview Deployment

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

[github-actions]

🎉 This PR is included in version 3.3.1 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 5.6.2 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[github-actions]

🎉 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 📦🚀

[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 📦🚀