feat: align the prop vocabulary and docs format with Kumo

[sriramveeraghanta]

Description

Extends the button-family rework (#239) and the menu/context-menu standardization (#241) across every component, adopting Kumo's prop vocabulary and its component-page format.

Props

Was	Now	Scope
magnitude	size	library-wide; sm·md·lg·xl value spellings unchanged
tone	variant	unions kept intact — Badge carries variant="danger" and variant="crimson" on one axis, exactly as Kumo's Badge does
emphasis	variant	Pill
appearance	variant	Tabs
presentation	appearance	NavigationMenuLink
mode	variant	Table — also corrects the root cva tableModes → tableVariants (rule 8)

Per-axis exported types follow (BadgeMagnitude/BadgeTone → BadgeSize/BadgeVariant), along with AVATAR_TONES → AVATAR_VARIANTS, getAvatarTone(Seed) → getAvatarVariant(Seed), avatarToneBgClass → avatarVariantBgClass, FieldOptionMagnitudeProvider/useFieldOptionMagnitude → FieldOptionSizeProvider/useFieldOptionSize, and TableMode/useTableMode → TableVariant/useTableVariant.

Deliberately not renamed — forcing these would break the API rather than align it:

• density stays. CheckboxGroupField/RadioGroupField take both density (option spacing) and magnitude (label text scale); both becoming size is a hard collision, and Kumo has no density vocabulary to borrow.
• sizing, fillType, surface, elevation, visibility, placement, layout stay — Kumo has no counterpart. orientation and side already matched.

The size rename collides with the native <input size> attribute exactly as the old rule 6b predicted. Kumo resolves this with Omit<…, "size">; the same fix is applied to Input, AutocompleteInput, NumberFieldInput, OTPFieldInput, and TextArea.

Docs

All 62 component pages reordered to Kumo's structure — lead demo → ## Installation → ## Usage → ## Examples (cases demoted to H3) → ## API Reference — each block wrapped in a new ComponentSection.

propel ships no barrel export (package.json exposes only granular subpaths), so Installation keeps a single granular block rather than Kumo's ### Barrel / ### Granular split, which would document imports that don't resolve. Worth adding a barrel later if full parity is wanted.

Protocol docs

packages/propel/AGENTS.md and docs/design.md still mandated the opposite convention (rule 6b banned native attribute names; rule 6c called variant "a smell"). Both rewritten, merged with the versions #241 landed. Also corrects six JSDoc examples still documenting the prominence prop dropped in #239.

Type of Change

• Improvement (refactor, restructure, or enhancement to existing functionality)
• Code refactoring
• Documentation update

This is a breaking change to the public API; a minor changeset is included (@makeplane/propel is pre-1.0).

Screenshots and Media

Test Scenarios

• Run the docs site and confirm each component page reads demo → Installation → Usage → Examples → API Reference, with example cases nested under ## Examples.
• Confirm the props table shows Prop · Type · Default · Description and marks required props with a red asterisk.
• Verify <Badge variant="danger"> and <Badge variant="crimson"> both render, confirming the mixed semantic/decorative union.
• Verify <Input size="lg" /> compiles and that the native size attribute is no longer accepted on Input, AutocompleteInput, NumberFieldInput, OTPFieldInput, TextArea.
• Verify CheckboxGroupField/RadioGroupField still accept density and size independently.
• Verify Table cells accept variant="table" / variant="spreadsheet" (previously mode).

References

Follows #239 (button-family API) and #241 (menu/context-menu API reference). Rebased onto both.

Verification: typecheck 0 errors, 848 tests passing across 120 files, format clean, and a structural validator over all 62 MDX pages (import resolution, unused imports, undefined JSX refs, balanced sections, PropsTable source paths, section order) reports 0 problems.

⚠️ pnpm build and pnpm check:lint could not be run locally — .node-version requires Node 24.16.0 and the dev machine has 22.17.1, so oxlint cannot load its .ts plugin and tsdown cannot load tsdown.config.ts. Both fail at config-load time on a clean tree too. CI should be treated as the source of truth for those two.

https://claude.ai/code/session_01G2g3qvyp1r5nDydrHk955N

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	propel-docs	fb6e7c5	Jul 26 2026, 11:17 AM

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[github-actions]

📚 Storybook preview: https://pr-242-propel-storybook.vamsi-906.workers.dev