Introduction
GWAN is an open-source component library and design system for Next.js projects. It provides 54 components and 217 icons with typed props, styled with Tailwind CSS v4 and themed with CSS variables, with light and dark mode built in.
Add one stylesheet with your colour tokens, and every component follows your brand and switches between light and dark mode.
54
Components
217
Icons
v1.0.11
Version
MIT
License
Installation
Install the package and Tailwind CSS v4, which compiles GWAN's class names in your app.
1. Install the package
npm install gwan-design-system2. Install Tailwind CSS v4
npm install tailwindcss@^4 @tailwindcss/postcssTailwind Setup
Tailwind CSS v4 is configured in CSS, so there is no tailwind.config.ts. It finds class names in your own files automatically but skips node_modules, so you add GWAN with @source.
1. Configure PostCSS
Create or update postcss.config.mjs at the root of your project.
// postcss.config.mjs
const config = {
plugins: {
"@tailwindcss/postcss": {},
},
};
export default config;2. Add the stylesheet
Put this in globals.css. It tells Tailwind where GWAN's classes are, makes dark: follow the .dark class, and defines the colour tokens. Change the hex values to your brand, but keep every token: the package ships no CSS, so a token you leave out has no value.
/* src/app/globals.css */
@import "tailwindcss";
/* GWAN's class names ship in its dist JavaScript. Tailwind skips node_modules,
so point it there. The path is relative to this CSS file. */
@source "../../node_modules/gwan-design-system/dist";
/* Make dark: utilities follow the .dark class instead of the OS setting. */
@custom-variant dark (&:where(.dark, .dark *));
/* ─── Light theme ─────────────────────────── */
:root {
--background: #f8f9f5;
--foreground: #1c2218;
--surface: #ffffff;
--surface-raised: #eef2e8;
--surface-overlay: #e3e9da;
--border: #c4cdb8;
--border-subtle: #d8dfce;
--primary-default: #435240;
--primary-default-fg: #f4f7f1;
--muted-fg: #60705a;
--accent: #0f766e;
--success: #047857;
--success-bg: #ecfdf5;
--success-fg: #064e3b;
--danger: #be123c;
--danger-bg: #fff1f2;
--danger-fg: #881337;
--warning: #b45309;
--warning-bg: #fffbeb;
--warning-fg: #78350f;
}
/* ─── Dark theme ──────────────────────────── */
.dark {
--background: #131a10;
--foreground: #e2eada;
--surface: #1c241a;
--surface-raised: #252e22;
--surface-overlay: #2d392a;
--border: #3c4d38;
--border-subtle: #2d392a;
--primary-default: #adc09e;
--primary-default-fg: #1c2218;
--muted-fg: #9ea593;
--accent: #2dd4bf;
--success: #34d399;
--success-bg: #022c1e;
--success-fg: #a7f3d0;
--danger: #fb7185;
--danger-bg: #200a10;
--danger-fg: #fecdd3;
--warning: #fbbf24;
--warning-bg: #1c1300;
--warning-fg: #fde68a;
}
/* ─── Register the tokens as Tailwind colours ─
inline: utilities read the token directly, so a
nested .dark section changes colour too. */
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-surface: var(--surface);
--color-surface-raised: var(--surface-raised);
--color-surface-overlay: var(--surface-overlay);
--color-border: var(--border);
--color-border-subtle: var(--border-subtle);
--color-primary-default: var(--primary-default);
--color-primary-default-fg: var(--primary-default-fg);
--color-muted-fg: var(--muted-fg);
--color-accent: var(--accent);
--color-success: var(--success);
--color-success-bg: var(--success-bg);
--color-success-fg: var(--success-fg);
--color-danger: var(--danger);
--color-danger-bg: var(--danger-bg);
--color-danger-fg: var(--danger-fg);
--color-warning: var(--warning);
--color-warning-bg: var(--warning-bg);
--color-warning-fg: var(--warning-fg);
}
/* Primary scale: the same in light and dark mode */
@theme {
--color-primary-50: #f4f7f1;
--color-primary-100: #e2eada;
--color-primary-200: #c8d5be;
--color-primary-300: #adc09e;
--color-primary-400: #a4b496;
--color-primary-500: #9ea593;
--color-primary-600: #7e8c73;
--color-primary-700: #60705a;
--color-primary-800: #435240;
--color-primary-900: #2c3629;
}@source path is relative to the CSS file. From src/app/globals.css it's ../../node_modules/…; adjust it if your stylesheet lives elsewhere. The registered tokens are normal utilities too: bg-background, text-foreground, border-border, bg-primary-500.:root, .dark and primary-scale blocks for you.Dark Mode
GWAN switches to its dark tokens whenever an ancestor has the dark class, normally <html>. The library doesn't toggle that class itself; your app does. In Next.js, next-themes handles it, including the system preference and remembering the choice. It's what gwan.dev uses.
1. Wrap your app with ThemeProvider
npm install next-themes// src/app/layout.tsx
import { ThemeProvider } from "next-themes";
export default function RootLayout({ children }) {
return (
<html lang="en" suppressHydrationWarning>
<body>
<ThemeProvider
attribute="class"
defaultTheme="system"
enableSystem
disableTransitionOnChange
>
{children}
</ThemeProvider>
</body>
</html>
);
}2. Add a theme toggle
Use the useTheme hook and guard against hydration mismatch with a mounted check.
"use client";
import { useTheme } from "next-themes";
import { useEffect, useState } from "react";
export function ThemeToggle() {
const { theme, setTheme } = useTheme();
const [mounted, setMounted] = useState(false);
useEffect(() => { setMounted(true); }, []);
if (!mounted) return null;
return (
<button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
{theme === "dark" ? "Light mode" : "Dark mode"}
</button>
);
}mounted before rendering theme-dependent UI. The server renders without knowing the user's preference, so reading theme before mount will produce a hydration mismatch.Using Vite
GWAN doesn't need Next.js. In a Vite app, use Tailwind's Vite plugin instead of PostCSS.
npm install tailwindcss@^4 @tailwindcss/vite// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
plugins: [react(), tailwindcss()],
});Put the stylesheet from Tailwind Setup in src/index.css, change its @source line to @source "../node_modules/gwan-design-system/dist";, and import it in src/main.tsx.
Dark mode without next-themes
Set the class before the page paints, then toggle it. This works in any React app.
<!-- index.html, inside <head> -->
<script>
const saved = localStorage.getItem("theme");
const dark = saved ? saved === "dark" : matchMedia("(prefers-color-scheme: dark)").matches;
document.documentElement.classList.toggle("dark", dark);
</script>import { Button } from "gwan-design-system";
export function ThemeToggle() {
const toggle = () => {
const dark = document.documentElement.classList.toggle("dark");
localStorage.setItem("theme", dark ? "dark" : "light");
};
return <Button label="Toggle theme" onClick={toggle} />;
}Using Components
Every GWAN component is a typed React function component. Import it from the package root and pass the required props. Components with fixed choices, such as variants, sizes and types, export an enum for them, so a wrong value is a type error.
Button
import { Button, BUTTON_VARIANTS } from "gwan-design-system";
<Button
variant={BUTTON_VARIANTS.PRIMARY}
label="Save Changes"
onClick={() => console.log("clicked")}
/>
<Button
variant={BUTTON_VARIANTS.SECONDARY}
label="Cancel"
onClick={() => {}}
disabled
/>Tag
import { Tag, TAG_TYPE } from "gwan-design-system";
<Tag type={TAG_TYPE.SUCCESS} label="Completed" />
<Tag type={TAG_TYPE.DANGER} label="Failed" />
<Tag type={TAG_TYPE.WARNING} label="Pending" />
<Tag type={TAG_TYPE.INFO} label="In Transit" />Avatar
import { Avatar, AVATAR_VARIANT } from "gwan-design-system";
// With image
<Avatar
name="Alex Chon"
email="alex@gwan.dev"
image="/images/profile.png"
variant={AVATAR_VARIANT.IMAGE_WITH_FULL}
/>
// Initials only
<Avatar
name="Sam Rivera"
email="sam@gwan.dev"
variant={AVATAR_VARIANT.INITIALS_ONLY}
/>Input
import { Input } from "gwan-design-system";
const [value, setValue] = useState("");
<Input
label="Email address"
type="email"
value={value}
placeholder="you@example.com"
onChange={(e) => setValue(e.target.value)}
onClear={value ? () => setValue("") : undefined}
/>Snackbar
import { Snackbar, SNACK_BAR_TYPE, CheckSVG } from "gwan-design-system";
<Snackbar
type={SNACK_BAR_TYPE.SUCCESS}
message="Profile updated successfully"
icon={<CheckSVG />}
/>Plug & Play
GWAN components are built to sit together. Below is a complete user profile card made only of GWAN components, plus one wrapper div for layout.
"use client";
import { useState } from "react";
import {
Avatar,
AVATAR_VARIANT,
Button,
BUTTON_VARIANTS,
CheckSVG,
Input,
Snackbar,
SNACK_BAR_TYPE,
Tag,
TAG_TYPE,
} from "gwan-design-system";
export default function ProfileCard() {
const [name, setName] = useState("Alex Chon");
const [saved, setSaved] = useState(false);
const handleSave = () => {
setSaved(true);
setTimeout(() => setSaved(false), 3000);
};
return (
<div className="bg-surface border border-border rounded-2xl p-6 flex flex-col gap-6 max-w-sm">
<Avatar
name={name}
email="alex@gwan.dev"
variant={AVATAR_VARIANT.INITIALS_WITH_FULL}
/>
<div className="flex gap-2">
<Tag type={TAG_TYPE.SUCCESS} label="Active" />
<Tag type={TAG_TYPE.INFO} label="Admin" />
</div>
<Input
label="Display name"
value={name}
onChange={(e) => setName(e.target.value)}
onClear={name ? () => setName("") : undefined}
/>
<Button
variant={BUTTON_VARIANTS.PRIMARY}
label="Save Changes"
leftIcon={<CheckSVG />}
onClick={handleSave}
/>
{saved && (
<Snackbar
type={SNACK_BAR_TYPE.SUCCESS}
message="Profile saved successfully"
icon={<CheckSVG />}
/>
)}
</div>
);
}That is the full component. There is no per-component theming: it follows light and dark mode through the CSS variables you define once in Getting Started.
Client vs Server Components
The package does not add "use client" to its build. Components that only display content render in a Server Component. Interactive ones, which use hooks or attach their own event handlers, must be imported from a file marked "use client". A few render on the server until you pass them a handler, because Server Components cannot pass functions.
| Component | In a Server Component | Reason |
|---|---|---|
| Accordion | ✗ Client only | useState for the open sections |
| Alert | ✗ Client only | useState for the dismissed state |
| Avatar | ✗ Client only | useState for the name tooltip |
| AvatarGroup | ✗ Client only | useState for the +N tooltip |
| Badge | ✓ Yes | No hooks |
| Banner | ✓ Yes | No hooks |
| Breadcrumb | ✓ Yes | No hooks |
| Button | ✗ Client only | Attaches onClick to its button |
| Callout | ✓ Yes | No hooks |
| Card | ✓ Yes | No hooks |
| Carousel | ✗ Client only | useState + useEffect for the slide index and auto-advance |
| Checkbox | ✗ Client only | Attaches its own change handler |
| Chip | ✗ Client only | Attaches onClear to its remove button |
| CircularProgress | ✓ Yes | No hooks |
| ColorPicker | ✗ Client only | useState + useEffect for the panel and hex field |
| CommandPalette | ✗ Client only | useState + useEffect for search and keyboard navigation |
| ContextMenu | ✗ Client only | useState + useEffect for cursor position and outside clicks |
| DatePicker | ✗ Client only | useState + useEffect for the calendar panel |
| DateRangePicker | ✗ Client only | useState + useEffect for the two-month calendar |
| Divider | ✓ Yes | No hooks |
| Drawer | ✗ Client only | useEffect to lock page scroll while open |
| DropdownMenu | ✗ Client only | useState + useEffect for the menu and outside clicks |
| Ellipsis | ✗ Client only | useState for the tooltip |
| FileUploader | ✗ Client only | useState + useRef for the file list, drag state and hidden input |
| FilterDropdown | ✗ Client only | useState for the panel |
| Icons | ✓ Yes | Plain SVG, no hooks |
| Input | ✗ Client only | Attaches its own key and paste handlers |
| List | ✓ Without handlers | No hooks; item onClick needs a Client Component |
| MenuBar | ✗ Client only | useState + useEffect for overflow and the mobile menu |
| Modal | ✗ Client only | useEffect + useRef for the focus trap and scroll lock |
| MultiSelect | ✗ Client only | useState + useEffect for the dropdown, search and keyboard navigation |
| NavBar | ✗ Client only | useState + useEffect for collapsing and tooltips |
| OtpInput | ✗ Client only | useRef for moving focus between digits |
| Pagination | ✗ Client only | useState for the page-size dropdown |
| Popover | ✗ Client only | useState + useEffect for open state and outside clicks |
| ProgressBar | ✓ Yes | No hooks |
| RadioButton | ✗ Client only | Attaches its own change handler |
| SearchInput | ✗ Client only | useEffect + useRef for the debounced search |
| SelectDropdown | ✗ Client only | useState + useEffect for the dropdown |
| Skeleton | ✓ Yes | No hooks |
| Slider | ✗ Client only | useState for the active thumb |
| Snackbar | ✓ Yes | No hooks; you decide when to render it |
| Spinner | ✓ Yes | No hooks; CSS animation |
| StatCard | ✓ Yes | No hooks |
| States | ✓ Yes | No hooks; built-in illustrations are inline SVG |
| Stepper | ✓ Yes | No hooks; you set each step's status |
| Switch | ✗ Client only | Attaches its own click handler |
| Table | ✓ Yes | No hooks; column render functions run where Table renders |
| Tabs | ✗ Client only | useRef + its own click and arrow-key handlers |
| Tag | ✓ Yes | No hooks |
| TextArea | ✓ Without handlers | No hooks; pass onChange or onClear from a Client Component |
| TextLink | ✓ Without handlers | Attaches onClick only if you pass one |
| TimeLine | ✓ Yes | No hooks |
| TimePicker | ✗ Client only | useState + useEffect for the scroll columns and outside clicks |
| Tooltip | ✓ Yes | No hooks; you control isVisible |
"use client" and import that file from your Server Component page, rather than marking the whole page client-side.Design Tokens
All tokens are CSS custom properties defined in :root and .dark. Overriding a token changes every component that references it — there is no cascading specificity to manage.
Semantic tokens
| Token | Light | Dark | Usage |
|---|---|---|---|
| --background | #f8f9f5 | #131a10 | Page background |
| --foreground | #1c2218 | #e2eada | Primary text |
| --surface | #ffffff | #1c241a | Cards, panels |
| --surface-raised | #eef2e8 | #252e22 | Elevated surfaces |
| --border | #c4cdb8 | #3c4d38 | All borders |
| --muted-fg | #60705a | #9ea593 | Secondary text |
| --accent | #0f766e | #2dd4bf | Links, highlights |
| --success | #047857 | #34d399 | Success states |
| --danger | #be123c | #fb7185 | Error states |
| --warning | #b45309 | #fbbf24 | Warning states |
Primary Colour Scale
The two semantic primary tokens (--primary-default and --primary-default-fg) control the main brand colour and follow light and dark mode. Primary buttons, tabs, the stepper, switches, progress bars and focus borders all use them, so they stay readable in both themes. A few places use fixed steps on the primary palette instead.
These scale steps are registered once in @theme {} and do not change between light and dark mode. If you rebrand to a different hue, replace the entire scale so the secondary and disabled buttons and the spinner track match your brand.
Components that use the primary scale
| Component | Scale steps used |
|---|---|
| Button | 100, 200, 300, 800 (secondary fill, hover, pressed, text); 200, 500 (disabled primary) |
| Spinner | 100 (track of the PRIMARY colour) |
Replacing the scale when rebranding
The Theme Generator includes a built-in scale builder — pick a seed colour and it auto-generates the full 10-step scale. Copy the output directly into your globals.css. To override manually, replace the values below.
/* In globals.css — replace ALL steps to match your brand hue */
@theme {
--color-primary-50: #f4f7f1; /* lightest tint */
--color-primary-100: #e2eada;
--color-primary-200: #c8d5be;
--color-primary-300: #adc09e;
--color-primary-400: #a4b496;
--color-primary-500: #9ea593; /* mid-point */
--color-primary-600: #7e8c73;
--color-primary-700: #60705a;
--color-primary-800: #435240;
--color-primary-900: #2c3629; /* darkest shade */
}Extending Themes
To rebrand GWAN for your project, override the CSS custom properties in your globals.css. You do not need to fork or patch the library — the components read whatever values you define.
Example: rebrand to an indigo palette
Change values in the stylesheet from Getting Started; keep every token name. This example changes the brand-related tokens and the primary scale, and leaves the rest as they were.
/* globals.css — edit the values, keep the rest of the stylesheet */
:root {
/* …other tokens unchanged… */
--primary-default: #4f46e5; /* indigo-600 */
--primary-default-fg: #ffffff;
--accent: #7c3aed; /* violet-600 */
}
.dark {
/* …other tokens unchanged… */
--primary-default: #818cf8; /* indigo-400 */
--primary-default-fg: #1e1b4b;
--accent: #a78bfa; /* violet-400 */
}
@theme {
/* …semantic mappings unchanged… */
--color-primary-50: #eef2ff;
--color-primary-100: #e0e7ff;
--color-primary-200: #c7d2fe;
--color-primary-300: #a5b4fc;
--color-primary-400: #818cf8;
--color-primary-500: #6366f1;
--color-primary-600: #4f46e5;
--color-primary-700: #4338ca;
--color-primary-800: #3730a3;
--color-primary-900: #312e81;
}Adding custom component styles
Every component accepts a className prop for one-off overrides without touching the source.
<Button
variant={BUTTON_VARIANTS.PRIMARY}
label="Wide CTA"
onClick={() => {}}
className="w-full py-4 text-lg"
/>Versioning
GWAN follows Semantic Versioning (semver) and is published to npm as gwan-design-system. Releases are listed on the GitHub releases page. To see which version your app has installed:
npm ls gwan-design-system© 2026 GWAN.DEV