docs(RadioGroup): scope Radio.Tabs to form fields

[tenphi]

Describe changes

Settles CUB-4129 — a docs-vs-guidance conflict, not a bug.

The RadioGroup Best Practices section said:

Visual Type: Use Radio.Tabs for compact toolbars, type="button" for spaced selections, traditional radios for forms

with a label="View" list/grid toolbar switcher as the example. Cloud's ui-review ruleset (radio-tabs-only-in-forms) says the opposite for exactly that case, so authors kept landing on PRs where a live doc line supported the choice the reviewer was asking them to change — it happened on two PRs the same day.

Resolved in favour of the Cloud rule, because the code backs it rather than the doc:

• Every RadioGroup variant — tabs included — runs through useFieldProps (RadioGroup.tsx:91) and wrapWithField (RadioGroup.tsx:178). Radio.Tabs is unavoidably a form control, carrying field wiring, role="radiogroup" semantics, and Form validation.
• Tabs already ships type="radio" (Tabs/types.ts:12), which renders the same chrome, owns the panels it switches between, and carries none of the field machinery.

A toolbar view switcher pays for wiring it never uses, so the doc line was the thing that was wrong.

Changes

RadioGroup.docs.mdx

• New When not to use section after When to Use, stating the form-control fact and carrying the ticket's decision matrix (in a Form + gates other controls → Radio.Tabs; in a Form otherwise → type="button"; not a Form → Tabs).
• Best Practice fix typings and minor issues #3 rewritten — the label="View" list/grid example that triggered this is now the explicit don't, shown beside its Tabs type="radio" replacement.
• Best Practice v0.3.0 #9 ("Tabs Mode") scoped to form fields.
• The Tabs Group example gained a one-line caveat and a name prop, since it is a field.

Tabs.docs.mdx

• The radio type bullet now names itself as the non-form choice and points back at Radio.Tabs, so the guidance holds from whichever doc an author lands on first.

Checklist

• Pipeline is passed
• Commit message follows commit guidelines

Not applicable — docs-only change, no runtime code touched: tests/stories, changeset (matching the precedent of fa0e4670, a docs-only .docs.mdx commit), library size threshold.

Closes: CUB-4129

Other information

• The ticket refers to docs/components/fields/RadioGroup.md; that file is generated from the .docs.mdx sources by scripts/prepare-docs.mjs at prepack, so the sources are what changed here. Regeneration was verified locally — the Storybook /docs/...--docs links rewrite to relative paths as intended.
• Worth a separate look: running scripts/prepare-docs.mjs outside prepack silently dirties the working tree. docs/glaze and docs/tasty are tracked as symlinks into node_modules, and the script replaces them with real copied directories (prepare-docs.mjs:439). Restored here, but it will catch out anyone who runs the script by hand.
• The other half of CUB-4129 is on the Cloud side: cubedevinc/cubejs-enterprise#14380 recorded a note that this doc line needed a caveat, and that note can now point at the doc instead of restating the decision.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only changes to .docs.mdx files; no runtime or API behavior is modified.

Overview
Aligns Storybook docs with Cloud’s radio-tabs-only-in-forms guidance so authors aren’t steered toward Radio.Tabs for toolbar-style view switchers.

In RadioGroup docs, it adds that every variant (including Radio.Tabs) is a form control, a When not to use section with a decision table (Form + gates fields → Radio.Tabs; in Form otherwise → type="button"; outside Form → Tabs with type="radio"), and rewrites Best Practices #3 and #9 so the old list/grid Radio.Tabs example is the explicit anti-pattern beside Tabs type="radio". The Tabs Group example now includes a name prop and a caveat about form-only use.

In Tabs docs, the radio type bullet now describes non-form compact switchers and cross-links to Radio.Tabs for form values.

^{Reviewed by Cursor Bugbot for commit e4e0916. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cube-ui-kit	Ready	Preview	Aug 27, 2026 9:45am

[changeset-bot]

⚠️ No Changeset found

Latest commit: e4e0916

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📦 NPM canary release

Deployed canary version 0.0.0-canary-cb8163d.

[github-actions]

🏋️ Size limit report

Name	Size	Passed?
All	500.28 KB (+0.01% 🔺)	Yes 🎉
Tree shaking (just a Button)	118.96 KB (0% 🟰)	Yes 🎉

Compared against main at b08530e — run 33004571191, 2026-08-26T19:19:48Z.

To see which modules changed, download the size-limit-statoscope-report artifact from this run and open report.html.

[github-actions]

🧪 Storybook is successfully deployed!

• 👀 Review changes: https://www.chromatic.com/build?appId=626ee6db91d1c8004a912249&number=4003
• 👨‍🎨 Preview storybook: https://626ee6db91d1c8004a912249-vhqarzmpyl.chromatic.com/