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

bash
npm install gwan-design-system

2. Install Tailwind CSS v4

bash
npm install tailwindcss@^4 @tailwindcss/postcss
NoteThe only peer dependency is React 19 or newer. GWAN is developed and tested in Next.js 16 with the App Router, and also works in Vite.

Tailwind 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.

js
// 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.

css
/* 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;
}
TipThe @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.
TipWant different colours? The Theme Generator builds the :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

bash
npm install next-themes
tsx
// 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.

tsx
"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>
  );
}
WarningAlways check 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.

bash
npm install tailwindcss@^4 @tailwindcss/vite
ts
// 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.

html
<!-- 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>
tsx
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

tsx
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

tsx
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

tsx
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

tsx
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

tsx
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.

tsx
"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.

ComponentIn a Server ComponentReason
Accordion✗ Client onlyuseState for the open sections
Alert✗ Client onlyuseState for the dismissed state
Avatar✗ Client onlyuseState for the name tooltip
AvatarGroup✗ Client onlyuseState for the +N tooltip
Badge✓ YesNo hooks
Banner✓ YesNo hooks
Breadcrumb✓ YesNo hooks
Button✗ Client onlyAttaches onClick to its button
Callout✓ YesNo hooks
Card✓ YesNo hooks
Carousel✗ Client onlyuseState + useEffect for the slide index and auto-advance
Checkbox✗ Client onlyAttaches its own change handler
Chip✗ Client onlyAttaches onClear to its remove button
CircularProgress✓ YesNo hooks
ColorPicker✗ Client onlyuseState + useEffect for the panel and hex field
CommandPalette✗ Client onlyuseState + useEffect for search and keyboard navigation
ContextMenu✗ Client onlyuseState + useEffect for cursor position and outside clicks
DatePicker✗ Client onlyuseState + useEffect for the calendar panel
DateRangePicker✗ Client onlyuseState + useEffect for the two-month calendar
Divider✓ YesNo hooks
Drawer✗ Client onlyuseEffect to lock page scroll while open
DropdownMenu✗ Client onlyuseState + useEffect for the menu and outside clicks
Ellipsis✗ Client onlyuseState for the tooltip
FileUploader✗ Client onlyuseState + useRef for the file list, drag state and hidden input
FilterDropdown✗ Client onlyuseState for the panel
Icons✓ YesPlain SVG, no hooks
Input✗ Client onlyAttaches its own key and paste handlers
List✓ Without handlersNo hooks; item onClick needs a Client Component
MenuBar✗ Client onlyuseState + useEffect for overflow and the mobile menu
Modal✗ Client onlyuseEffect + useRef for the focus trap and scroll lock
MultiSelect✗ Client onlyuseState + useEffect for the dropdown, search and keyboard navigation
NavBar✗ Client onlyuseState + useEffect for collapsing and tooltips
OtpInput✗ Client onlyuseRef for moving focus between digits
Pagination✗ Client onlyuseState for the page-size dropdown
Popover✗ Client onlyuseState + useEffect for open state and outside clicks
ProgressBar✓ YesNo hooks
RadioButton✗ Client onlyAttaches its own change handler
SearchInput✗ Client onlyuseEffect + useRef for the debounced search
SelectDropdown✗ Client onlyuseState + useEffect for the dropdown
Skeleton✓ YesNo hooks
Slider✗ Client onlyuseState for the active thumb
Snackbar✓ YesNo hooks; you decide when to render it
Spinner✓ YesNo hooks; CSS animation
StatCard✓ YesNo hooks
States✓ YesNo hooks; built-in illustrations are inline SVG
Stepper✓ YesNo hooks; you set each step's status
Switch✗ Client onlyAttaches its own click handler
Table✓ YesNo hooks; column render functions run where Table renders
Tabs✗ Client onlyuseRef + its own click and arrow-key handlers
Tag✓ YesNo hooks
TextArea✓ Without handlersNo hooks; pass onChange or onClear from a Client Component
TextLink✓ Without handlersAttaches onClick only if you pass one
TimeLine✓ YesNo hooks
TimePicker✗ Client onlyuseState + useEffect for the scroll columns and outside clicks
Tooltip✓ YesNo hooks; you control isVisible
TipPut client-only components in their own file marked "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

TokenLightDarkUsage
--background#f8f9f5#131a10Page background
--foreground#1c2218#e2eadaPrimary text
--surface#ffffff#1c241aCards, panels
--surface-raised#eef2e8#252e22Elevated surfaces
--border#c4cdb8#3c4d38All borders
--muted-fg#60705a#9ea593Secondary text
--accent#0f766e#2dd4bfLinks, highlights
--success#047857#34d399Success states
--danger#be123c#fb7185Error states
--warning#b45309#fbbf24Warning 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

ComponentScale steps used
Button100, 200, 300, 800 (secondary fill, hover, pressed, text); 200, 500 (disabled primary)
Spinner100 (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.

css
/* 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  */
}
TipAlways replace all 10 steps together. Using only a few steps from a different hue creates inconsistent hover and disabled states across components. Use the Theme Generator to generate a matched scale from a single seed colour.

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.

css
/* 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;
}
WarningThe package ships no CSS, so there are no built-in values to fall back to. Every token in the Getting Started stylesheet must stay defined; a missing one leaves that colour unset wherever a component uses it.

Adding custom component styles

Every component accepts a className prop for one-off overrides without touching the source.

tsx
<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:

bash
npm ls gwan-design-system
NoteBreaking changes are communicated via a major version bump. Minor versions add new components or tokens. Patch versions are bug fixes and documentation updates.

© 2026 GWAN.DEV