Get Started
Installation
# npm
npm install pine-design-system
# yarn
yarn add pine-design-system
# pnpm
pnpm add pine-design-systemReact 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
| Prop | Type | Default | Description |
|---|---|---|---|
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. |
syncWithSystem | boolean | true | Follows the OS color scheme when theme is uncontrolled. Set to false to use defaultTheme instead. |
primaryColor | string | — | Hex color to customize the primary palette (e.g. "#6366f1"). |
<ThemeProvider design="game" defaultTheme="dark">
{/* Game style + dark mode */}
</ThemeProvider>Next Steps
- Foundation: Token structure (colors, typography, spacing)
- Components: Component list and usage