@widgli/colors

Professional color palette system for the Widgli design system. This package provides a comprehensive set of color tokens, CSS custom properties, and TypeScript definitions for consistent theming across applications.

Features

• 🎨 Comprehensive Color Palette - Light, dark, and semantic color schemes
• 🌙 Dark Mode Support - Built-in dark mode color variants
• 📱 Accessibility Focused - WCAG AA compliant color combinations
• 🚀 TypeScript Ready - Full type definitions for all color tokens
• 🎯 CSS Custom Properties - Easy integration with CSS-in-JS frameworks
• 📦 Tree Shakeable - Only import the colors you need

Installation

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

Usage

JavaScript/TypeScript

import { light, dark, blackA, whiteA } from '@widgli/colors';

// Use color values directly
const primaryColor = light.sky.sky9;
const darkBackground = dark.slate.slate1;

// Alpha variants for overlays and transparency
const overlay = blackA.blackA8;
const highlight = whiteA.whiteA8;

CSS

@import '@widgli/colors/dist/index.css';

.my-component {
  background-color: var(--color-sky-9);
  color: var(--color-slate-1);
}

Tailwind CSS v4

@import 'tailwindcss';

@theme {
  /* Use Widgli color tokens */
  --color-sky-1: var(--color-sky-1);
  --color-sky-2: var(--color-sky-2);
  --color-sky-3: var(--color-sky-3);
  --color-sky-4: var(--color-sky-4);
  --color-sky-5: var(--color-sky-5);
  --color-sky-6: var(--color-sky-6);
  --color-sky-7: var(--color-sky-7);
  --color-sky-8: var(--color-sky-8);
  --color-sky-9: var(--color-sky-9);
  --color-sky-10: var(--color-sky-10);
  --color-sky-11: var(--color-sky-11);
  --color-sky-12: var(--color-sky-12);

  /* And so on for other color scales */
}

Color Scale

Each color follows a 1-12 scale where:

• 1-3: Lightest shades (backgrounds, subtle borders)
• 4-6: Light shades (surfaces, secondary text)
• 7-9: Medium shades (primary text, borders)
• 10-12: Darkest shades (emphasis, primary actions)

Available Color Palettes

Light Theme

• light.sky.* - Primary blue colors
• light.slate.* - Neutral grays
• light.green.* - Success states
• light.red.* - Error states
• light.amber.* - Warning states

Dark Theme

• dark.sky.* - Primary blue colors (dark optimized)
• dark.slate.* - Neutral grays (dark optimized)
• dark.green.* - Success states (dark optimized)
• dark.red.* - Error states (dark optimized)
• dark.amber.* - Warning states (dark optimized)

Alpha Variants

• blackA.* - Black with alpha transparency
• whiteA.* - White with alpha transparency

API Reference

Color Objects

interface ColorScale {
  1: string;
  2: string;
  3: string;
  4: string;
  5: string;
  6: string;
  7: string;
  8: string;
  9: string;
  10: string;
  11: string;
  12: string;
}

interface ColorPalette {
  sky: ColorScale;
  slate: ColorScale;
  green: ColorScale;
  red: ColorScale;
  amber: ColorScale;
}

CSS Custom Properties

All colors are available as CSS custom properties:

:root {
  --color-sky-1: hsl(193, 100%, 98.8%);
  --color-sky-2: hsl(193, 100%, 96.3%);
  --color-sky-3: hsl(193, 100%, 91.8%);
  /* ... and so on */
}

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.2 → 0.0.3) - bug fixes
pnpm version:patch

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

# Major version (0.0.2 → 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/colors --dry-run
node scripts/publish.js @widgli/colors

Commit Convention

Follow conventional commits for automatic changelog generation:

# Features
git commit -m "feat: add new color palette"

# Bug fixes
git commit -m "fix: correct color contrast ratio"

# 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