Skip to Content
Get Started

Get Started

Installation

# npm npm install pine-design-system # yarn yarn add pine-design-system # pnpm pnpm add pine-design-system

React 18 or higher is required.

Basic Usage

Wrap your app root with ThemeProvider and import the stylesheet once.

import { ThemeProvider, Button } from "pine-design-system"; import "pine-design-system/style.css"; export default function App() { return ( <ThemeProvider defaultDesign="basic"> <Button intent="primary">Click me</Button> </ThemeProvider> ); }

Next.js / React Server Components

The main pine-design-system entry ships as a client boundary ("use client") — every component and ThemeProvider depend on React context and hooks. Use it from a Client Component, or render it as JSX from a Server Component (a server tree rendering a client subtree, the normal RSC pattern) — both work fine. It’s not safe to import from pine-design-system and read its exports as plain values inside server-only code (a Server Component’s function body, a Route Handler, generateMetadata, etc.).

For that, import design tokens from the pine-design-system/tokens subpath instead — it has no React or DOM dependency and carries no "use client" directive:

// Safe in server-only logic — no React/DOM dependency import { radius, colors } from "pine-design-system/tokens";

Avoiding a theme flash under SSR

syncWithSystem (on by default) is SSR-safe: the server and the client’s first render always agree, so there’s no hydration mismatch. What you do get on a real SSR app is one brief correction right after hydration, where the theme flips from the fallback to the real OS preference — this is unavoidable without knowing the client’s OS setting at request time.

To skip that flash entirely, inline getThemeInitScript() (from pine-design-system/tokens) in your root <head>, before hydration runs. It reads prefers-color-scheme synchronously and paints the right theme class on <html> immediately:

// app/layout.tsx (Server Component) import { getThemeInitScript } from "pine-design-system/tokens"; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en" suppressHydrationWarning> <head> <script dangerouslySetInnerHTML={{ __html: getThemeInitScript({ design: "game" }) }} /> </head> <body>{children}</body> </html> ); }

suppressHydrationWarning on <html> is required — add it yourself, the package can’t add it for you. This is the same pattern libraries like next-themes use.

ThemeProvider Options

PropTypeDefaultDescription
defaultDesign"basic" | "game" | "crayon""basic"Initial design concept (uncontrolled).
design"basic" | "game" | "crayon"—Design concept (controlled). Use with onDesignChange.
defaultTheme"light" | "dark"—Initial color mode (uncontrolled).
theme"light" | "dark"—Color mode (controlled). Use with onThemeChange.
syncWithSystembooleantrueFollows the OS color scheme when theme is uncontrolled. Set to false to use defaultTheme instead.
primaryColorstring—Hex color to customize the primary palette (e.g. "#6366f1").
<ThemeProvider design="game" defaultTheme="dark"> {/* Game style + dark mode */} </ThemeProvider>

Next Steps

Last updated on