@widgli/themes

Professional design system themes and CSS utilities for Widgli. This package provides a comprehensive set of design tokens, CSS custom properties, utility classes, and TypeScript definitions for building consistent, accessible, and beautiful user interfaces.

Features

• 🎨 Design Tokens - Comprehensive system of colors, spacing, typography, and more
• 🌙 Theme System - Light, dark, and system theme support
• 🚀 Tailwind CSS v4 - Built specifically for Tailwind CSS v4 with modern CSS features
• 📱 Responsive Design - Container queries and responsive utilities
• ♿ Accessibility First - WCAG compliant with focus states and motion preferences
• 🎯 TypeScript Ready - Full type definitions for all design tokens
• 📦 Modular Architecture - Import only what you need
• 🎭 Custom Variants - Dark mode and translucent panel variants

Installation

npm install @widgli/themes
# or
yarn add @widgli/themes
# or
pnpm add @widgli/themes

Quick Start

CSS Import

/* Import the main theme CSS */
@import '@widgli/themes/index.css';

/* Or import specific parts */
@import '@widgli/themes/breakpoints.css';

JavaScript/TypeScript

import { cn, widgliClass, responsive } from '@widgli/themes';
import { FONT_FAMILIES, FONT_WEIGHTS } from '@widgli/themes/fonts';

// Use utility functions
const buttonClasses = cn(
  'px-4 py-2 rounded-md',
  'bg-sky-500 text-white',
  'hover:bg-sky-600',
);

// Use theme-aware classes
const cardClasses = widgliClass('widgli-card', {
  elevated: true,
  interactive: true,
});

// Use responsive utilities
const layoutClasses = responsive('grid', {
  sm: 'grid-cols-2',
  lg: 'grid-cols-3',
});

Design Tokens

Colors

The package provides a comprehensive color system with light and dark variants:

:root {
  /* Primary colors */
  --color-sky-1: hsl(193, 100%, 98.8%);
  --color-sky-9: hsl(193, 100%, 50%);

  /* Neutral colors */
  --color-slate-1: hsl(0, 0%, 99%);
  --color-slate-12: hsl(0, 0%, 9%);

  /* Semantic colors */
  --color-green-9: hsl(142, 76%, 36%);
  --color-red-9: hsl(0, 84%, 60%);
  --color-amber-9: hsl(48, 96%, 53%);
}

Spacing

Consistent spacing scale for layouts and components:

:root {
  --spacing-1: 0.25rem; /* 4px */
  --spacing-2: 0.5rem; /* 8px */
  --spacing-3: 0.75rem; /* 12px */
  --spacing-4: 1rem; /* 16px */
  --spacing-5: 1.25rem; /* 20px */
  --spacing-6: 1.5rem; /* 24px */
  --spacing-7: 1.75rem; /* 28px */
  --spacing-8: 2rem; /* 32px */
  --spacing-9: 2.25rem; /* 36px */
}

Typography

Comprehensive typography system with font families, sizes, and weights:

:root {
  /* Font families */
  --font-widgli-sans: 'Widgli Sans';
  --font-widgli-serif: 'Widgli Serif';
  --font-widgli-mono: 'Widgli Mono';

  /* Font sizes */
  --text-1: 0.75rem; /* 12px */
  --text-2: 0.875rem; /* 14px */
  --text-3: 1rem; /* 16px */
  --text-4: 1.125rem; /* 18px */
  --text-5: 1.25rem; /* 20px */
  --text-6: 1.5rem; /* 24px */
  --text-7: 1.875rem; /* 30px */
  --text-8: 2.25rem; /* 36px */
  --text-9: 3rem; /* 48px */
}

Breakpoints

Modern breakpoint system with container queries:

@custom-media --xs (min-width: 520px);
@custom-media --sm (min-width: 768px);
@custom-media --md (min-width: 1024px);
@custom-media --lg (min-width: 1280px);
@custom-media --xl (min-width: 1640px);

Utility Functions

cn() - Class Name Utility

Merge CSS classes with conflict resolution:

import { cn } from '@widgli/themes';

const buttonClasses = cn(
  'px-4 py-2 rounded-md',
  'bg-blue-500 hover:bg-blue-600',
  'text-white font-medium',
);

widgliClass() - Theme-Aware Classes

Create theme-aware component classes:

import { widgliClass } from '@widgli/themes';

const cardClasses = widgliClass('widgli-card', {
  elevated: true,
  interactive: true,
  size: 'large',
});
// Result: "widgli-card widgli-card--elevated widgli-card--interactive widgli-card--size-large"

responsive() - Responsive Utilities

Create responsive class combinations:

import { responsive } from '@widgli/themes';

const gridClasses = responsive('grid', {
  sm: 'grid-cols-2',
  md: 'grid-cols-3',
  lg: 'grid-cols-4',
});
// Result: "grid sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4"

Theme Variants

Dark Mode

Built-in dark mode support with CSS custom properties:

@custom-variant dark (&:where(.dark, .dark *));

.dark {
  color-scheme: dark;
}

/* Dark mode colors are automatically applied */

Translucent Panels

Support for translucent and solid panel backgrounds:

@custom-variant translucent (&:where([data-panel-background="translucent"] *));
@custom-variant solid (&:where([data-panel-background="solid"] *));

CSS Utilities

The package includes a comprehensive set of utility classes:

Layout Utilities

.widgli-container {
  width: 100%;
  margin-left: auto;
  margin-right: auto;
  padding-left: var(--spacing-4);
  padding-right: var(--spacing-4);
}

.widgli-grid {
  display: grid;
  gap: var(--spacing-4);
}

.widgli-flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}

Typography Utilities

.widgli-text-heading {
  font-family: var(--font-widgli-serif);
  font-weight: var(--font-weight-medium);
  line-height: var(--line-height-tight);
}

.widgli-text-body {
  font-family: var(--font-widgli-sans);
  font-weight: var(--font-weight-normal);
  line-height: var(--line-height-relaxed);
}

Animation Utilities

.widgli-animate-fade-in {
  animation: fade-in var(--duration-normal) ease-out;
}

.widgli-animate-slide-up {
  animation: slide-up var(--duration-normal) ease-out;
}

Integration with Tailwind CSS v4

This package is specifically designed for Tailwind CSS v4 with CSS-only configuration:

@import 'tailwindcss';
@plugin "@tailwindcss/typography";
@plugin "tailwindcss-animate";

@theme {
  /* Use Widgli design tokens */
  --color-primary: var(--color-sky-9);
  --color-secondary: var(--color-slate-9);
  --spacing-4: var(--spacing-4);
  --font-sans: var(--font-widgli-sans);
}

Modern CSS Features

Container Queries

Built-in support for modern container queries:

.widgli-card {
  container-type: inline-size;
}

.widgli-card-content {
  padding: var(--spacing-4);
}

@container (min-width: 400px) {
  .widgli-card-content {
    padding: var(--spacing-6);
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: var(--spacing-4);
  }
}

CSS Custom Properties

Dynamic theming with CSS custom properties:

:root {
  --widgli-primary: 210 100% 50%;
  --widgli-secondary: 270 100% 50%;
  --widgli-accent: 210 100% 60%;
}

.component {
  background-color: hsl(var(--widgli-primary));
  color: hsl(var(--widgli-secondary));
}

API Reference

Main Exports

// Utility functions
export { cn, widgliClass, responsive };

// Font utilities
export { FONT_FAMILIES, FONT_WEIGHTS, FONT_FEATURES };

// Types
export type { ThemeConfig, ColorScheme, SpacingScale, TypographyScale };

CSS Exports

// Main CSS file
import '@widgli/themes/index.css';

// Specific CSS files
import '@widgli/themes/breakpoints.css';
import '@widgli/themes/fonts/default/index.css';

Publishing Workflow

This package uses semantic versioning and automated changelog generation. Here's how to publish updates:

Prerequisites

# Install dependencies
pnpm install

# Ensure you have npm access
npm whoami

Version Management

# Patch version (0.0.1 → 0.0.2) - bug fixes
pnpm version:patch

# Minor version (0.0.1 → 0.1.0) - new features
pnpm version:minor

# Major version (0.0.1 → 1.0.0) - breaking changes
pnpm version:major

Changelog Generation

# Generate changelog for current version
pnpm changelog

# Generate changelog from the beginning
pnpm changelog:first

Publishing

# Dry run (test without publishing)
pnpm publish:patch    # Test patch release
pnpm publish:minor    # Test minor release
pnpm publish:major    # Test major release

# Actual release
pnpm release:patch    # Publish patch release
pnpm release:minor    # Publish minor release
pnpm release:major    # Publish major release

Root-Level Publishing

You can also use the root monorepo publishing script:

# From the root directory
node scripts/publish.js @widgli/themes --dry-run
node scripts/publish.js @widgli/themes

Commit Convention

Follow conventional commits for automatic changelog generation:

# Features
git commit -m "feat: add new theme variant"

# Bug fixes
git commit -m "fix: correct spacing scale values"

# Documentation
git commit -m "docs: update usage examples"

# Breaking changes
git commit -m "feat!: change color scale from 1-12 to 1-10"

Release Checklist

Before publishing:

1. ✅ Run pnpm typecheck - ensure TypeScript compilation passes
2. ✅ Run pnpm lint - ensure code quality standards
3. ✅ Run pnpm build - ensure build succeeds
4. ✅ Update CHANGELOG.md if needed
5. ✅ Test with pnpm publish:dry (patch/minor/major)
6. ✅ Commit version bump and changelog
7. ✅ Run pnpm release:patch (or minor/major)

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT © Widgli Team