Skip to content

Installation

Check requirements and explore an illustrative package setup.

Requirements

Gumdrop is a styling and component layer, not a framework — it drops into any React 19 project. The only hard requirement is Tailwind v4, because the tokens register through its @theme inline mapping.

  • Requirement
    React
    Version
    19.0+
    Notes
    Peer dependency; the primitives use Base UI.
  • Requirement
    Tailwind CSS
    Version
    v4
    Notes
    Tokens register through @theme inline in globals.css.
  • Requirement
    Next.js
    Version
    16 (recommended)
    Notes
    Any React 19 framework works; docs assume the App Router.
  • Requirement
    Node.js
    Version
    20.9+
    Notes
    Required by the build toolchain, not the runtime.

Install the package

These illustrative, unpublished package names are not runnable install targets. Follow this repository’s README to run the actual checkout. The sample splits into two packages: @gumdrop/system for the primitives and @gumdrop/tokens for the token stylesheet. Pick your package manager:

pnpm addbash
pnpm add @gumdrop/system @gumdrop/tokens

Then import the stylesheet once — in a root layout for App Router apps, or in your entry file for other frameworks:

app/layout.tsxtsx
import "@gumdrop/tokens/globals.css"import { ThemeProvider } from "@gumdrop/system" export default function RootLayout({ children }) {  return (    <html lang="en" data-theme="light">      <body>        <ThemeProvider initialTheme="light">{children}</ThemeProvider>      </body>    </html>  )}

One stylesheet, two themes

The token layer ships light and dark together. Set data-theme on <html> to override the OS preference — no second stylesheet to import.

Verify the install

Render a button and confirm it resolves the accent: the fill should track --primary-default, and the label --primary-foreground. You can also open this site's Design tokens page and switch a brand preset — if your button follows, the token layer is wired.

app/page.tsxtsx
import { Button } from "@gumdrop/system"

export default function Page() {
  return <Button>Hello, tokens</Button>
}

Next steps

  • Explore the token model before styling anything — the semantic families decide how color, type, and geometry resolve.
  • Read Components for the primitive inventory and the copy-don't-import workflow for sections.
  • If you are upgrading from v1.9, the changelog notes the v2 breaking changes.