@gwenui/themes

The foundational design system layer for GwenUI. This package provides a standardized set of OKLCH-based design tokens, self-hosted typography, and seamless Tailwind CSS v4 integration designed for high-end digital experiences.

✨ Features

Modern Color Space — Built entirely on OKLCH for superior color mixing and perceptual uniformity.
Dynamic Theming — Seamless Light and Dark mode via CSS custom properties.
Typography Engine — Self-hosted Plus Jakarta Sans, Lora, and Space Mono with zero external requests.
Tailwind v4 Ready — Native @theme architecture, no tailwind.config.ts required.

🚀 Installation

# pnpm (recommended)
pnpm add @gwenui/themes

# npm
npm install @gwenui/themes

# yarn
yarn add @gwenui/themes

🛠️ Integration

Import both layers into your global CSS entry point:

/* src/styles/globals.css */
@import "tailwindcss";
@import "@gwenui/themes/tokens";
@import "@gwenui/themes/fonts";

Then map the tokens into Tailwind's @theme block:

@theme inline {
  /* Typography */
  --font-sans:    var(--font-sans);
  --font-serif:   var(--font-serif);
  --font-mono:    var(--font-mono);
  --font-heading: var(--font-serif);

  /* Colors */
  --color-background:        var(--background);
  --color-foreground:        var(--foreground);
  --color-primary:           var(--primary);
  --color-primary-foreground:var(--primary-foreground);
  --color-border:            var(--border);
  /* ... map other tokens as needed */
}

Note: @gwenui/themes is designed for Tailwind CSS v4. It does not use or require tailwind.config.ts.

📂 Package Structure

@gwenui/themes/
├── src/
│   ├── css/
│   │   ├── tokens.css          # OKLCH design tokens — light & dark
│   │   └── fonts.css           # @font-face declarations
│   └── fonts/
│       ├── PlusJakartaSans/    # PlusJakartaSans-[Weight].ttf
│       ├── Lora/               # Lora-[Weight].ttf
│       └── SpaceMono/          # SpaceMono-[Weight].ttf
├── package.json
└── README.md

🎨 Design Tokens

All tokens are defined as CSS custom properties and follow the OKLCH color space.

Core Tokens

Token	Light	Dark
`--background`	`oklch(97% 0.010 85)`	`oklch(15% 0.05 295)`
`--foreground`	`oklch(15% 0.020 48)`	`oklch(98.5% 0 0)`
`--primary`	`oklch(75% 0.18 48)`	`oklch(75% 0.18 48)`
`--border`	`oklch(55% 0.22 300 / 20%)`	`oklch(55% 0.22 300 / 20%)`
`--radius`	`0.625rem`	`0.625rem`

Typography Tokens

Token	Value
`--font-sans`	`'Plus Jakarta Sans', ui-sans-serif, system-ui, sans-serif`
`--font-serif`	`'Lora', ui-serif, serif`
`--font-mono`	`'Space Mono', ui-monospace, monospace`

🖋️ Typography Setup

Self-hosted fonts are included in the package. The @font-face rules in fonts.css automatically link to the CSS variables --font-sans, --font-serif, and --font-mono.

Font file naming convention:

Plus Jakarta Sans — PlusJakartaSans-[Weight].ttf
Lora — Lora-[Weight].ttf
Space Mono — SpaceMono-[Weight].ttf

🌗 Dark Mode

Dark mode is applied via the .dark class on any parent element:

<html class="dark">
  ...
</html>

All tokens automatically cascade to their dark variants. No additional configuration needed.

📄 License

Distributed under the MIT License. See LICENSE for more information.

Built with precision by JinXSuper 🧡