fix: address migration feedback from shadcn/Radix to Kumo by geoquant · Pull Request #42 · cloudflare/kumo

geoquant · 2026-02-07T22:54:01Z

Summary

Addresses issues surfaced during a ~70-component migration from shadcn/ui + Radix to Kumo.

Changes

Bugs

CLI doc/docs/ls broken — fixed registry path from catalog/ to ai/, replaced internal error message with consumer-facing text
Tailwind 4 @source missing from docs — fixed inconsistent Usage Example on installation page, added @source docs to package README

Type safety

Dialog DTS leaks @base-ui/react — wrapped sub-components (Root, Trigger, Title, Description, Close) in thin functions using ComponentPropsWithoutRef, matching Popover's pattern
Button aria-label on icon-only — discriminated union requires aria-label when shape="square" or shape="circle"

Accessibility

Label rendered <span> — changed to <label> with htmlFor support

Discoverability

Textarea alias for InputArea
ToastProvider alias for Toasty

Documentation

Added confirmation dialog recipe showing disablePointerDismissal
Updated Select basic example to use items prop
Documented icon-only button pattern with aria-label

Not addressed

Dialog.Close render prop verbosity — intentional Base UI design decision, not a Kumo concern

CiscoFran10 · 2026-02-08T03:23:43Z

packages/kumo-docs-astro/src/pages/installation.astro

        </p>
        <CodeBlock
-          code={`@import "tailwindcss";
+          code={`@source "../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}";


The @source "../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}" example assumes a specific project structure.

It might be worth adding a short disclaimer noting that this path is relative to the user’s config file and may need adjustment. For example, if the app lives under /src, the relative path would differ (e.g. ../../node_modules/...), and copying the snippet verbatim could fail.

see issue #33

CiscoFran10 · 2026-02-08T03:26:31Z

packages/kumo/README.md

-```js
-// Explicit import (recommended)
-import "@cloudflare/kumo/styles/tailwind";
+**Important:** Tailwind CSS v4 does not scan `node_modules/` by default. You must add a `@source` directive so Tailwind can discover the utility classes used by Kumo components. Without this, components may render with missing styles (e.g. Dialogs not centered).


Would it also make sense to add this on the docs installation page?

ascorbic

Great stuff, thanks

ascorbic · 2026-02-08T07:24:39Z

packages/kumo/ai/component-registry.json

Did this mean to remove all the props?

ascorbic · 2026-02-08T07:31:54Z

packages/kumo-docs-astro/src/pages/components/dialog.astro

+        <Heading level={3}>Confirmation Dialog (Alert)</Heading>
+        <p class="mb-3 text-sm text-kumo-strong">
+          For confirmation dialogs that should not be dismissed by clicking outside (similar to an AlertDialog),
+          use <code class="rounded bg-kumo-control px-1 py-0.5 text-xs">disablePointerDismissal</code> on <code class="rounded bg-kumo-control px-1 py-0.5 text-xs">Dialog.Root</code>. 


Does disablePointerDismissal also disable escape key dismissal?

@ascorbic From my testing... no, disablePointerDismissal does not disable Escape key dismissal.

That actually seems like the correct behavior if we want to align with alertdialog patterns. Pressing Esc should be equivalent to activating the Cancel / Discard action and should return focus to the trigger, per the ARIA Authoring Practices:
https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/examples/alertdialog/

Also, the prop name explicitly refers to pointer dismissal, so it makes sense that it only blocks outside pointer interactions, not keyboard dismissal via Esc.

ascorbic · 2026-02-08T07:42:31Z

packages/kumo-docs-astro/src/pages/installation.astro

+          code={`@source "../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}";
+@import "tailwindcss";
 @import "@cloudflare/kumo/styles/tailwind";`}


#44 says that the Kumo styles need to be imported before Tailwind. Which is correct? https://github.com/cloudflare/kumo/pull/44/changes#diff-aea0502ee64cb7178c22c4c0aa01d2d6dd14e33da259a2dbc934bd7a485cef8dR17-R18

@source

…mples The Usage Example section on the installation page was missing the @source directive, causing consumers following that example to get silently broken styles (e.g. Dialogs rendering in top-left corner). Also adds @source documentation to the package README, which previously had no mention of this requirement. Fixes stale 'catalog/' path reference in README.

The CLI was looking for the component registry at 'catalog/' but the file is at 'ai/component-registry.json'. This caused all three documentation commands to fail with a misleading error referencing an internal build script (pnpm build:ai-metadata) that doesn't exist. Fixed path from 'catalog' to 'ai' and replaced the internal error message with a consumer-facing one.

…ences Dialog was the only compound component that directly assigned Base UI sub-components without wrapping them, causing generated .d.ts files to emit 'typeof DialogBase.Root' references that leak @base-ui/react into downstream consumers' type resolution. Now wraps Root, Trigger, Title, Description, and Close in thin wrapper functions (matching the pattern used by Popover) so the emitted types use ComponentPropsWithoutRef instead of direct typeof references. Also exports the new sub-component prop types for library consumers.

…ssal Adds a 'Confirmation Dialog (Alert)' example to the Dialog docs page that demonstrates using disablePointerDismissal on Dialog.Root to prevent overlay dismissal — the Kumo equivalent of AlertDialog. This addresses the discoverability gap where users migrating from Radix/shadcn don't know how to create non-dismissible confirmation dialogs.

The Label component rendered a <span> which doesn't create an accessible association with its form control. Changed the standalone rendering to use a <label> element and added the htmlFor prop so consumers can associate the label with a specific form control. The asContent mode still renders a <span> since it's used inside another element (like Field) that handles accessibility.

Exports InputArea as Textarea from both the component path and the main barrel export for discoverability. Consumers searching for 'textarea' in autocomplete or docs will now find the component.

Exports Toasty as ToastProvider for discoverability. Consumers searching for 'toast provider' or 'ToastProvider' (the standard name in other UI libraries) will now find the component.

The basic Select example showed value and label being identical (value='Apple', children='Apple') which masked the fact that without the items prop, the trigger displays the raw value string. Updated to use lowercase values with items prop so the correct pattern is shown first, with an explanation of what items controls.

The icon-only button example didn't include aria-label, teaching an inaccessible pattern. Added explanation text about the accessibility requirement and updated both the code example and demo to include aria-label on shape='square' and shape='circle' buttons.

…ed union When shape is 'square' or 'circle', TypeScript now requires aria-label at the type level. This catches silent accessibility bugs where icon-only buttons have no screen reader label. Regular buttons with shape='base' (the default) are unaffected.

Adds a Vite plugin that rewires @cloudflare/kumo imports to raw source files during astro dev, enabling instant HMR without rebuilding the kumo package. Production builds still use dist/ exports to validate the real consumer experience.

@source

Address review feedback: - Add warning callout about Tailwind v4 requiring @source directive - Add note that @source path is relative to CSS file location - Apply to both installation docs page and README

The codegen script only handled intersection types (allOf) and plain properties, causing discriminated unions like ButtonProps to produce empty props. Now merges properties from all union members, marking props as optional when they don't appear in every member. Regenerated registry with --no-cache to restore Button's 14 props.

@theme

Kumo's @theme tokens must be registered before Tailwind processes them, so @import "@cloudflare/kumo/styles" must come before @import "tailwindcss". Fixed all code snippets in the installation page and README to match the working order used in the docs site's own global.css.

geoquant force-pushed the geoquant/kumo-fixes-for-matt branch 2 times, most recently from cff2086 to b73546c Compare February 7, 2026 22:57

CiscoFran10 reviewed Feb 8, 2026

View reviewed changes

ascorbic reviewed Feb 8, 2026

View reviewed changes

ascorbic mentioned this pull request Feb 8, 2026

feat(kumo): add JSDoc to all components and AI usage guide #44

Open

5 tasks

geoquant force-pushed the geoquant/kumo-fixes-for-matt branch from 80f97b9 to e2ab2c8 Compare February 9, 2026 19:32

rozenmd approved these changes Feb 9, 2026

View reviewed changes

jonnie-clouds added 15 commits February 9, 2026 12:59

feat(input): add Textarea alias for InputArea

92be40d

Exports InputArea as Textarea from both the component path and the main barrel export for discoverability. Consumers searching for 'textarea' in autocomplete or docs will now find the component.

feat(toast): add ToastProvider alias for Toasty

2871202

Exports Toasty as ToastProvider for discoverability. Consumers searching for 'toast provider' or 'ToastProvider' (the standard name in other UI libraries) will now find the component.

chore: add changeset for migration feedback fixes

ab5e089

docs: add @source path disclaimer and Tailwind v4 callout

36314ce

Address review feedback: - Add warning callout about Tailwind v4 requiring @source directive - Add note that @source path is relative to CSS file location - Apply to both installation docs page and README

geoquant force-pushed the geoquant/kumo-fixes-for-matt branch from b10af05 to 93cc97a Compare February 9, 2026 20:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: address migration feedback from shadcn/Radix to Kumo#42

fix: address migration feedback from shadcn/Radix to Kumo#42
geoquant wants to merge 15 commits intocloudflare:mainfrom
geoquant:geoquant/kumo-fixes-for-matt

geoquant commented Feb 7, 2026

Uh oh!

CiscoFran10 Feb 8, 2026

Uh oh!

CiscoFran10 Feb 8, 2026

Uh oh!

ascorbic left a comment

Uh oh!

ascorbic Feb 8, 2026

Uh oh!

ascorbic Feb 8, 2026

Uh oh!

CiscoFran10 Feb 8, 2026

Uh oh!

ascorbic Feb 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

geoquant commented Feb 7, 2026

Summary

Changes

Not addressed

Uh oh!

CiscoFran10 Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

CiscoFran10 Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

ascorbic left a comment

Choose a reason for hiding this comment

Uh oh!

ascorbic Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

ascorbic Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

CiscoFran10 Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

ascorbic Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants