# What Is Kumo UI? Inside Cloudflare's Open-Source React Design System

Explore Kumo UI, Cloudflare's open-source React design system. Learn about its components, AI tools, installation, charts, and shadcn/ui alternatives.

Canonical URL: https://aiidelist.com/blog/what-is-kumo-ui-cloudflare-react-design-system

Language: en

Published: 2026-10-08

Updated: 2026-10-08

Kumo UI is an open-source React component library developed by Cloudflare for building modern web applications, SaaS dashboards, and developer tools. Built on Base UI and designed around reusable visual patterns, it combines accessible components, semantic design tokens, data visualization, and AI-friendly developer tooling.

Unlike component libraries that provide only basic buttons and form elements, Kumo aims to offer a more complete foundation for building complex application interfaces. Its ecosystem includes ready-to-use components, customizable page blocks, a command-line interface, a machine-readable component registry, and a design skill for AI coding agents.

The official website is kumo-ui.com, and the project is available under the MIT license on GitHub.

## Key Takeaways

- **Kumo UI is Cloudflare's open-source React component library**, designed primarily for modern applications and dashboard interfaces.
- **Built on Base UI:** Its components inherit accessible interaction primitives, including keyboard navigation, focus management, and ARIA support.
- **54 components in the published registry:** The official component registry covers form inputs, navigation, overlays, layouts, charts, and other application patterns as of October 2026.
- **Tailwind CSS v4 integration:** Kumo uses semantic design tokens and supports light and dark themes.
- **AI-friendly development:** The component registry, CLI documentation commands, and official design skill help coding agents understand the available components and their APIs.
- **Advanced data visualization:** Kumo includes ECharts-based time-series charts, Sankey diagrams, geographic maps, and an SVG-based globe.
- **Components and Blocks use different distribution models:** Components are imported from npm, while Blocks can be installed as editable source code.
- **Free for commercial use:** The MIT license permits use in commercial applications, subject to its license terms.
- **Best suited for SaaS and developer tools:** Kumo is particularly attractive for dashboards, resource management systems, analytics products, and API platforms.

## What Is Kumo UI? is a React design system maintained by Cloudflare. It provides reusable interface components with a consistent visual language inspired by modern developer-focused applications.

The project addresses a common challenge in frontend development: creating a polished, consistent interface without repeatedly rebuilding buttons, inputs, tables, navigation menus, dialogs, and other essential application elements.

A typical SaaS application requires more than a collection of attractive components. It needs consistent interaction behavior, accessible navigation, responsive layouts, visual feedback, loading states, and a unified approach to design tokens.

Kumo attempts to bring these requirements together in one component ecosystem.

Its technology stack includes:

- **React and TypeScript** for the primary component implementation.
- **Base UI** for accessible, unstyled interaction primitives.
- **Tailwind CSS v4** for component styling and integration.
- **CSS custom properties** for semantic color tokens and themes.
- **Phosphor Icons** for iconography.
- **Apache ECharts** for advanced charts and data visualization.
- **Astro** for the documentation website and a separate Astro component implementation.

The project is not a full application framework. It does not replace routing, authentication, databases, backend APIs, or state management. Instead, it provides the presentation and interaction layer that applications can build upon.

## Why Did Cloudflare Build Kumo UI?

Developer platforms frequently expose complicated workflows through web interfaces.

A cloud management dashboard, for example, may need to display deployments, request statistics, configuration settings, access tokens, resource inventories, and account permissions.

Building every interface independently creates several problems:

- Inconsistent component styling between product areas.
- Repeated accessibility and interaction work.
- Different implementations of common behaviors.
- Increased maintenance costs as applications grow.
- Difficulties keeping design specifications aligned with production code.

Kumo addresses these challenges by establishing a shared component vocabulary.

A button, confirmation dialog, navigation sidebar, or resource table can follow the same underlying design rules throughout an application.

The important distinction is that Kumo is an opinionated design system rather than an entirely unstyled toolkit. This reduces the initial design work for applications that fit its visual language, although products with highly distinctive branding may require additional customization.

Kumo should not be interpreted as a complete copy of Cloudflare's production dashboard. It is a separately distributed component library with its own documented APIs, releases, and development roadmap.

## Kumo UI Components: What Is Included?

As of October 2026, Kumo's official machine-readable registry lists 54 components across nine categories. The documentation also organizes components into practical sections for everyday UI development, data visualization, and higher-level page compositions.

The exact count can change between releases and may differ depending on whether internal primitives, subcomponents, and Blocks are included.

**Forms and inputs**

Kumo includes Input, InputArea, InputGroup, Checkbox, Radio, Switch, Select, Combobox, Autocomplete, DatePicker, and TagInput.

These components support common application tasks such as entering configuration values, selecting resources, managing tags, and submitting forms.

**Navigation and layout**

Sidebar, Breadcrumbs, Tabs, Pagination, Grid, LayerCard, Toolbar, and CommandPalette help organize complex application interfaces.

The Sidebar component is particularly relevant for SaaS dashboards. It supports collapsible groups, icon-only navigation, responsive mobile layouts, and additional navigation behaviors.

**Feedback and overlays**

Dialog, LayerDialog, Popover, Tooltip, Banner, Badge, Toast, Loader, and related components help communicate application state and present secondary interactions.

LayerDialog is designed to handle responsive dialog behavior, including mobile drawer-style presentation.

**Developer-focused components**

SensitiveInput, ClipboardText, InlineCopyText, and code display components are useful for interfaces involving API credentials, resource identifiers, configuration values, and technical documentation.

For example, a developer platform can display an API token in SensitiveInput and allow users to reveal or copy it through a consistent interaction pattern.

**Data visualization**

Kumo includes TimeseriesChart, SankeyChart, BubbleMap, ChoroplethMap, and GlobeMap, alongside lower-level chart utilities.

These components make the library especially relevant for analytics and infrastructure dashboards.

Developers can explore the available APIs and examples through the official component registry.

## Components vs. Blocks: An Important Architectural Difference

Kumo supports two approaches to distributing UI code.

**Components are installed through npm.**

They are imported from the Kumo package and receive changes through package version updates. This approach is useful when teams want consistent components without maintaining copies of their implementations.

**Blocks are installed through the Kumo CLI.**

Blocks are higher-level UI compositions whose source code is copied into the application. Developers can then modify them to match specific business requirements.

The official Block catalog includes Page Header, Resource List, and Delete Resource.

For example, Delete Resource provides a confirmation flow that requires users to enter a resource name before completing a destructive action.

This pattern is valuable for infrastructure applications because accidental deletion can have significant consequences.

To initialize Kumo's Block configuration and install a Block, run:

```bash
npx @cloudflare/kumo init
npx @cloudflare/kumo blocks
npx @cloudflare/kumo add PageHeader
```

A copied Block can be edited directly inside the project, while normal Kumo components remain package-managed dependencies.

**The trade-off:** Package components simplify centralized maintenance, while source-owned Blocks provide deeper customization but also place responsibility for future updates on the application developer.

## How to Install Kumo UI in a React Project

Kumo is distributed through the public npm registry as `@cloudflare/kumo`.

The official installation documentation lists version 2.14.0 as of October 8, 2026.

A React application can install Kumo using pnpm:

```bash
pnpm add @cloudflare/kumo
pnpm add react react-dom @phosphor-icons/react
```

Existing React projects may already include React and React DOM.

### Configure Tailwind CSS v4

For applications using Tailwind CSS v4, configure the main stylesheet with the required imports and source-scanning directive:

```css
@source '../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}';
@import '@cloudflare/kumo/styles/tailwind';
@import 'tailwindcss';
```

The `@source` path must be adjusted relative to the location of the CSS file.

This step is important because Tailwind CSS v4 does not automatically scan dependencies inside `node_modules` for utility classes.

Without the correct source configuration, some Kumo components may render with incomplete styling. For instance, an overlay may appear incorrectly positioned even though its React component loads successfully.

### Import and render components

A simple React component can use Kumo's built-in form controls and card styling:

```tsx
import { Button, Input, LayerCard } from '@cloudflare/kumo';

export function CreateProjectPanel() {
  return (
    <LayerCard className='p-6'>
      <h2 className='mb-4 text-lg font-semibold'>
        Create a project
      </h2>
      <div className='space-y-4'>
        <Input
          label='Project name'
          placeholder='My application'
        />
        <Button variant='primary'>
          Create project
        </Button>
      </div>
    </LayerCard>
  );
}
```

This example demonstrates component composition and styling. A production form would additionally require state management, validation, submission handling, and appropriate error feedback.

### Use granular imports

For applications concerned about bundle size, Kumo supports component-level imports:

```tsx
import { Button } from '@cloudflare/kumo/components/button';
import { Input } from '@cloudflare/kumo/components/input';
```

Granular imports help bundlers avoid including unrelated components. Actual bundle savings still depend on the build tool, dependencies, and application usage.

### Use Kumo without Tailwind CSS

Applications that do not use Tailwind can import the standalone stylesheet:

```tsx
import '@cloudflare/kumo/styles/standalone';
```

This build includes precompiled component styles, removing the need for Tailwind configuration in the consuming application.

### Avoid popup stacking problems

Kumo's floating components use portals for elements such as dropdowns, dialogs, and popovers.

Because these elements can interact with application stacking contexts, the documentation recommends isolating the application root.

```css
#root {
  isolation: isolate;
}
```

This helps prevent elements with positive `z-index` values, such as sticky navigation headers, from appearing above open popups.

The installation guide explains this behavior and the recommended configuration.

## Kumo UI Design Tokens and Dark Mode

Kumo uses semantic design tokens rather than requiring every component to reference fixed colors.

Instead of hardcoding a gray background or blue text color, developers can apply classes that describe an element's purpose.

Examples include:

- `bg-kumo-canvas` for the outer application background.
- `bg-kumo-base` for standard component surfaces.
- `bg-kumo-elevated` for raised surfaces.
- `text-kumo-default` for primary text.
- `text-kumo-subtle` for secondary descriptions.
- `bg-kumo-brand` for primary branded controls.
- `border-kumo-hairline` for subtle visual boundaries.

This approach separates visual meaning from specific color values.

It also allows the same components to adapt to different themes without developers manually changing every individual class.

Kumo controls light and dark mode through the `data-mode` attribute.

For example:

```html
<html data-mode='dark'>
  <body>
    <!-- Application content -->
  </body>
</html>
```

The design system uses semantic color definitions that respond to the selected mode. Developers are encouraged to use these tokens instead of relying on arbitrary Tailwind colors and manual `dark:` variants.

Kumo also documents theme overrides, including a FedRAMP-oriented theme.

For teams maintaining multiple applications, semantic tokens are particularly useful because typography, surfaces, contrast, and visual hierarchy can remain consistent even when individual brand colors change.

However, adopting an opinionated design system can also limit visual freedom. Applications with highly customized illustrations, unusual typography, or distinctive marketing layouts may require a separate frontend design approach.

## Kumo UI Charts: Beyond Basic Interface Components

One of Kumo's distinguishing capabilities is its data visualization ecosystem.

Many React component libraries focus primarily on forms, dialogs, menus, and navigation. Kumo additionally provides components tailored to analytical dashboards.

**TimeseriesChart** supports time-based line and bar charts, making it suitable for request volumes, API latency trends, usage history, and other time-dependent measurements.

The component expects data points represented as timestamp-and-value pairs. For example, timestamps are supplied in milliseconds.

**SankeyChart** visualizes relationships and flows between categories or systems. Possible applications include traffic sources, user conversion paths, and resource movement.

**BubbleMap and ChoroplethMap** support geographic visualization, making them useful for regional analytics or infrastructure location data.

**GlobeMap** provides a three-dimensional-looking globe rendered with SVG rather than WebGL. This distinction matters because it does not require a WebGL rendering context or the ECharts dependency used by the planar map components.

Kumo's chart documentation demonstrates integration with Apache ECharts. Developers should account for the additional ECharts dependency when using the relevant chart components.

A practical architectural recommendation is to load complex charts only on pages where they are needed, rather than adding the complete visualization stack to an application's initial bundle.

The official chart examples provide implementation details and customization options.

## How Kumo UI Supports AI Coding Agents

Kumo includes several features intended to make UI development more reliable when performed by AI coding assistants.

This is an important distinction from libraries that rely entirely on human-readable documentation.

### Machine-readable component registry

The Kumo component registry is generated from TypeScript definitions and component examples.

It documents component names, available properties, variants, defaults, example usage, and semantic design tokens.

Developers and AI agents can retrieve the registry through an HTTP endpoint:

```bash
curl https://kumo-ui.com/api/component-registry
```

The registry provides structured information that a coding agent can use instead of guessing component APIs.

For example, when generating a settings page, an agent can inspect the supported Input and Select properties before producing JSX.

This reduces the risk of suggesting nonexistent props or unsupported component variants, although generated code still requires verification.

### Component documentation through the CLI

Kumo also exposes component documentation directly through command-line commands:

```bash
npx @cloudflare/kumo ls
npx @cloudflare/kumo doc Button
npx @cloudflare/kumo docs
```

These commands are useful for developers working in terminal-based coding environments.

A coding assistant can inspect the available component interfaces before implementing a page instead of relying solely on previously learned examples.

### Kumo Design Skill

Cloudflare provides an additional design skill for compatible AI coding agents.

It can be installed using:

```bash
npx skills add cloudflare/kumo@kumo-design
```

The skill documents concrete interface conventions, including typography, spacing, font weight, and visual hierarchy.

For example, the documented guidelines recommend 14px text for routine interface content, sentence-case headings, and consistent typography without unnecessary character-spacing adjustments.

These rules help AI-generated interfaces maintain a coherent visual language.

**Why this matters:** AI coding tools can generate functioning React components quickly, but visual inconsistency remains a common problem when interfaces are created without shared design rules.

A structured registry combined with explicit design guidance makes it easier to generate pages that follow existing component contracts.

It does not guarantee that generated applications are accessible, responsive, secure, or visually correct. Human review and automated testing remain necessary.

## Kumo UI and Figma Integration

Kumo also includes resources for generating Figma components from the component system.

Its Figma tooling uses structured component definitions to create design assets that correspond to the implementation in code.

This approach can reduce drift between product designs and frontend implementation.

For example, a design team can work with ComponentSets representing the same component variants available in React, rather than manually reproducing unrelated versions of each element.

The official documentation currently describes a development workflow involving local plugin builds and installation through Figma's development plugin interface.

That is different from assuming that a fully hosted, one-click public Figma Community plugin is available.

Developers interested in this workflow should follow the Kumo Figma documentation and confirm the current tooling requirements.

## Kumo UI vs. shadcn/ui vs. Base UI

Kumo is frequently compared with other React UI solutions, especially shadcn/ui and Base UI.

Although these projects share some underlying technologies, they approach component ownership and design customization differently.

| Feature | Kumo UI | shadcn/ui | Base UI |
|---|---|---|---|
| Primary purpose | Opinionated application design system | Customizable component source collection | Unstyled accessible primitives |
| Default styling | Cloudflare-inspired visual system | Configurable Tailwind-based styles | No predefined styling |
| Distribution | npm components and CLI-installed Blocks | Source code installed through CLI | npm package |
| Component ownership | Package-managed components; Blocks are editable | Application owns installed component code | Library-managed primitives |
| Customization | Design tokens, themes, props, and Blocks | Direct component source editing | Full custom styling |
| Accessibility | Built on Base UI | Base UI or Radix-based components | Accessibility-focused primitives |
| Data visualization | Integrated chart components | Usually additional chart libraries | Not a primary focus |
| Best use case | SaaS dashboards and developer platforms | Custom web applications and design systems | Building custom component systems |

An important 2026 development is that shadcn/ui made Base UI the default for newly initialized projects in July 2026, while continuing to support Radix.

Therefore, Kumo and modern shadcn/ui projects may share the same underlying accessibility primitives.

**Choose Kumo when:** A product needs a consistent dashboard interface quickly, especially one involving settings, resource management, charts, and developer workflows.

**Choose shadcn/ui when:** Full control over component source code and long-term brand customization are higher priorities.

**Choose Base UI directly when:** The team intends to build its own visual design system and needs accessible interaction primitives without predefined styling.

Kumo's competitive advantage is not that it replaces every other component ecosystem. It offers a specific combination of visual consistency, developer-focused components, and AI-readable implementation guidance.

## Does Kumo UI Work With Astro?

Yes, but the integration method matters.

The main `@cloudflare/kumo` package is designed for React.

Astro projects using React islands can integrate React components, subject to the application's React integration and hydration requirements.

Cloudflare also maintains a separate package named `@cloudflare/kumo-astro`.

This package provides Astro-native components using `.astro` files and framework-independent browser behaviors where needed.

The Astro package does not require React for its native components.

Installation:

```bash
pnpm add @cloudflare/kumo-astro astro
```

Example:

```astro
---
import Button from '@cloudflare/kumo-astro/components/button';
import '@cloudflare/kumo-astro/styles';
---

<Button variant='primary'>
  Get started
</Button>
```

This makes the project relevant to developers building lightweight Astro applications or documentation interfaces.

However, the Astro implementation and React package should not be assumed to have identical component coverage or APIs.

Before adopting the Astro package across a large project, developers should verify required components, available exports, interactive behavior, and browser compatibility.

The implementation is documented in the Cloudflare Kumo Astro repository.

## What's New in Kumo UI 2.14.0?

As of October 8, 2026, the latest release listed by the official documentation and GitHub releases page is version 2.14.0, published on September 17, 2026.

This release expanded several areas of the component system.

Notable changes include:

- **ButtonGroup:** A component for visually joining related buttons, including split-button layouts.
- **TagInput:** A control for entering and removing collections of free-form values.
- **InlineCopyText:** A compact copy control for identifiers and values displayed in dense interfaces.
- **LayerDialog:** Responsive dialog behavior with mobile drawer support and dismissal handling.
- **TimeseriesChart improvements:** Additional Y-axis interval configuration and tooltip functionality.
- **Sidebar updates:** Additional callbacks associated with navigation state transitions.
- **Base UI dependency update:** Integration with Base UI 1.8.0.

These updates highlight Kumo's continuing focus on complex application workflows rather than only basic visual components.

Developers should consult the official changelog before upgrading production applications, especially when changes affect component behavior or dependencies.

## Kumo UI Advantages

**1. Consistent interface design**

Kumo provides an established system for typography, colors, spacing, and interaction patterns. This can reduce design inconsistencies across large applications.

**2. Accessible component foundations**

Base UI handles many complex interaction behaviors, including keyboard navigation and focus management. This reduces the amount of accessibility infrastructure developers must implement independently.

**3. Useful dashboard components**

The combination of navigation, tables, input controls, status indicators, and charts makes Kumo attractive for administration and analytics interfaces.

**4. AI-assisted development support**

Structured component metadata and explicit design guidance help coding agents use the library more accurately.

**5. Multiple distribution approaches**

Teams can use versioned npm components for consistency and source-owned Blocks when deeper customization is necessary.

**6. Open-source licensing**

The MIT license allows commercial use and modification, provided the relevant license conditions are respected.

## Kumo UI Limitations and Potential Drawbacks

Kumo is not the ideal solution for every frontend project.

**Opinionated visual language:** Its default styling is optimized for a particular type of application. Highly distinctive brands may require substantial theme customization.

**React-first ecosystem:** The main library targets React. Although an Astro implementation exists, developers using Vue, Svelte, or other frameworks cannot assume equivalent first-party component coverage.

**Additional visualization dependencies:** Advanced charts can introduce ECharts and related code into the application bundle.

**Package-managed component ownership:** Unlike a source-first component collection, ordinary Kumo npm components are updated through dependency upgrades rather than direct modification of locally owned source files.

**Limited page-block catalog:** The publicly documented Blocks catalog remains relatively focused. Developers needing complete authentication, billing, and CRM page templates may still need to implement substantial application-specific layouts.

**Integration considerations:** Existing applications may encounter CSS conflicts, popup stacking issues, font differences, or overlapping theme conventions.

**Accessibility is not automatic compliance:** Base UI provides accessible foundations, but teams must still provide meaningful labels, test screen-reader behavior, verify focus order, and check color contrast.

These limitations do not make Kumo unsuitable for production, but they should influence technical evaluation and adoption plans.

## Common Kumo UI Problems and How to Fix Them

**Problem: Components render without their expected styles.**

Check the Tailwind CSS v4 setup, particularly the `@source` directive and its relative path. Ensure the Kumo stylesheet is imported in the documented order.

**Problem: A dropdown or dialog appears behind a sticky header.**

Review application stacking contexts and apply `isolation: isolate` to the application root as recommended by the installation guide.

**Problem: Dark mode does not match the application setting.**

Check whether the correct `data-mode` value is applied to an ancestor element. Prefer Kumo semantic tokens instead of manually combining unrelated color utilities.

**Problem: A component property suggested by an AI coding assistant does not exist.**

Inspect the component documentation through the CLI or registry before making changes. TypeScript validation should be part of the development workflow.

**Problem: A chart increases the application bundle size.**

Use granular imports, review ECharts imports, and consider lazy-loading chart-heavy pages.

**Problem: An Astro component behaves differently from its React equivalent.**

Confirm the package-specific implementation, supported props, and required browser scripts. The Astro implementation should not automatically be treated as a drop-in replacement for every React component.

**Problem: Upgrading a Kumo dependency changes component behavior.**

Pin dependency versions when stability is important, review release notes, and test navigation, forms, overlays, and accessibility behavior before deployment.

## Who Should Use Kumo UI?

Kumo is particularly well suited to applications where consistency and developer productivity are important.

**SaaS founders and independent developers** can use it to build account dashboards, subscription management interfaces, configuration pages, and product administration tools.

**AI product developers** can use Kumo for model selection interfaces, generation task queues, usage analytics, API key management, and resource administration.

**Developer platform teams** can benefit from technical components designed for infrastructure dashboards, logs, deployments, settings, and operational data.

**Analytics product teams** may find the charting components useful for request metrics, conversion trends, and usage reports.

**Teams using AI coding agents** can take advantage of the registry and design skill to improve consistency in generated interfaces.

Conversely, content-heavy blogs, highly animated landing pages, experimental creative websites, and browser games may gain less benefit from adopting the complete Kumo design system.

For those projects, a smaller component layer or fully customized frontend may be more appropriate.

## Frequently Asked Questions

**Is Kumo UI free?**

Yes. Kumo is open source under the MIT license, which generally permits commercial use, distribution, and modification subject to the license terms.

**Is Kumo UI made by Cloudflare?**

Yes. The official project is maintained under Cloudflare's GitHub organization and published through the `@cloudflare/kumo` npm package.

**Does Kumo UI require React?**

The primary package requires React. A separate Astro-native implementation is available through `@cloudflare/kumo-astro`.

**Does Kumo UI use Tailwind CSS?**

Yes. Kumo integrates with Tailwind CSS v4, but it also provides a standalone precompiled stylesheet for projects that do not use Tailwind.

**Is Kumo UI better than shadcn/ui?**

Neither is universally better. Kumo provides a more opinionated package-based application design system, while shadcn/ui emphasizes customizable, locally owned component code. The better choice depends on project requirements and maintenance preferences.

**Does Kumo UI support dark mode?**

Yes. It uses semantic design tokens and supports light and dark modes through the `data-mode` attribute.

**Can Kumo UI be used with AI coding assistants?**

Yes. Its machine-readable registry, CLI documentation, and design skill are intended to make component usage easier for compatible coding agents.

**Does Kumo UI include dashboard templates?**

Kumo provides components and selected higher-level Blocks suitable for dashboards. It is not a complete SaaS application template with authentication, billing, backend services, and database integrations included.

**Is Kumo UI the same as Kuma UI or Kumu?**

No. Kumo UI is Cloudflare's React component library. Kuma UI is a separate styling project, while Kumu is associated with relationship mapping and visualization. These similarly named projects serve different purposes.

## Conclusion

Kumo UI is more than a collection of pre-styled React components. It combines accessible Base UI primitives, a consistent visual design system, application-focused components, data visualization tools, and AI-readable development resources.

Its strongest value proposition is the ability to create cohesive SaaS dashboards and developer interfaces without repeatedly rebuilding the same frontend foundations.

The addition of a component registry, command-line documentation, AI design skill, and Figma tooling also reflects a broader shift in frontend development: component libraries are increasingly being designed for both human developers and AI coding agents.

However, Kumo's opinionated visual system, React-first architecture, and package-managed components mean it will not replace every existing UI solution.

For teams building analytics dashboards, infrastructure consoles, AI applications, or multi-product SaaS platforms, it deserves serious consideration.

**Explore the Kumo UI documentation, review its GitHub repository, and test a small dashboard interface before adopting it across a production application.**