@puppuccino/colors

Color types, palettes, and theming for terminal applications.

Installation

npm install @puppuccino/colors

Or install from GitHub:

npm install github:averagejoeslab/colors

Features

• Color Types - ANSI, 256-color, and RGB color representations
• Color Conversion - Convert between color formats
• Palettes - Pre-built color palettes for consistent styling
• Themes - Light and dark theme definitions
• Color Utilities - Lighten, darken, blend colors

Usage

Color Types

import {
  AnsiColor,
  Color256,
  RGBColor,
  createColor
} from '@puppuccino/colors';

// ANSI 16 colors
const red = AnsiColor.Red;
const brightBlue = AnsiColor.BrightBlue;

// 256-color palette
const color = Color256.from(196);  // Bright red

// RGB colors
const orange = RGBColor.from(255, 165, 0);
const hex = RGBColor.fromHex('#FF5500');

// Create color from various inputs
const c1 = createColor('red');           // ANSI red
const c2 = createColor(196);             // 256-color
const c3 = createColor('#FF5500');       // RGB from hex
const c4 = createColor([255, 85, 0]);    // RGB from array

Color Conversion

import { toAnsi, to256, toRGB, toHex } from '@puppuccino/colors';

const rgb = RGBColor.from(255, 100, 50);

// Convert to different formats
const ansi = toAnsi(rgb);      // Nearest ANSI color
const c256 = to256(rgb);       // Nearest 256-color
const hex = toHex(rgb);        // '#FF6432'

// Convert 256 to RGB
const fromPalette = toRGB(Color256.from(196));

Palettes

import { Palette, createPalette } from '@puppuccino/colors';

// Use built-in palette
console.log(Palette.primary);    // Primary color
console.log(Palette.secondary);  // Secondary color
console.log(Palette.success);    // Green
console.log(Palette.warning);    // Yellow
console.log(Palette.error);      // Red
console.log(Palette.info);       // Blue

// Create custom palette
const myPalette = createPalette({
  brand: '#FF5500',
  accent: '#00AAFF',
  muted: [128, 128, 128],
});

Themes

import {
  Theme,
  DarkTheme,
  LightTheme,
  createTheme
} from '@puppuccino/colors';

// Use built-in themes
const dark = DarkTheme;
console.log(dark.foreground);    // Text color
console.log(dark.background);    // Background color
console.log(dark.accent);        // Accent color
console.log(dark.muted);         // Muted/dimmed color

// Create custom theme
const myTheme = createTheme({
  foreground: '#FFFFFF',
  background: '#1A1A2E',
  accent: '#E94560',
  muted: '#666666',

  // Semantic colors
  success: '#4CAF50',
  warning: '#FFC107',
  error: '#F44336',
  info: '#2196F3',
});

Color Utilities

import {
  lighten,
  darken,
  blend,
  contrast,
  isLight,
  isDark
} from '@puppuccino/colors';

const color = RGBColor.from(100, 150, 200);

// Adjust brightness
const lighter = lighten(color, 0.2);   // 20% lighter
const darker = darken(color, 0.3);     // 30% darker

// Blend two colors
const blended = blend(color1, color2, 0.5);  // 50/50 mix

// Check contrast ratio (for accessibility)
const ratio = contrast(foreground, background);
console.log(`Contrast ratio: ${ratio}:1`);

// Check if color is light or dark
if (isLight(background)) {
  // Use dark text
} else {
  // Use light text
}

Adaptive Colors

import { adaptive, getSystemTheme } from '@puppuccino/colors';

// Get system preference
const systemTheme = getSystemTheme();  // 'light' | 'dark'

// Create color that adapts to theme
const text = adaptive({
  light: '#333333',
  dark: '#EEEEEE',
});

// Use current theme
console.log(text.current);  // Returns appropriate color

API Reference

Color Types

• AnsiColor - 16 ANSI color constants
• Color256 - 256-color palette wrapper
• RGBColor - RGB color with utilities
• createColor() - Create color from various inputs

Conversion Functions

• toAnsi(color) - Convert to nearest ANSI color
• to256(color) - Convert to nearest 256-color
• toRGB(color) - Convert to RGB
• toHex(color) - Convert to hex string

Palette & Theme

• Palette - Default color palette
• createPalette() - Create custom palette
• DarkTheme / LightTheme - Built-in themes
• createTheme() - Create custom theme

Utilities

• lighten(color, amount) - Make color lighter
• darken(color, amount) - Make color darker
• blend(c1, c2, ratio) - Blend two colors
• contrast(fg, bg) - Calculate contrast ratio
• isLight(color) - Check if color is light
• isDark(color) - Check if color is dark

License

MIT