@pastel-palette/colors

Core color definitions package for the UI Color System, featuring OKLCH color space support, TypeScript types, and a kawaii aesthetic.

Installation

npm install @pastel-palette/colors

Usage

Basic Usage

import { colorSystem } from '@pastel-palette/colors'

// Access regular colors
const blueLight = colorSystem.regular.blue.light
console.log(blueLight.oklch) // "oklch(0.85 0.12 237)"
console.log(blueLight.srgb) // "rgb(173 207 255)"
console.log(blueLight.p3) // "color(display-p3 0.678 0.812 1.0)"

// Access semantic colors
const primaryText = colorSystem.element.text.primary.light
const background = colorSystem.background.primary.dark

Type Definitions

import type {
  ColorValue,
  ColorVariants,
  SemanticColor,
  DepthLevel,
} from '@pastel-palette/colors'

// Color value with multiple formats
interface ColorValue {
  oklch: string // Primary format
  srgb: string // Fallback for older browsers
  p3?: string // Optional P3 color space
}

// Light and dark variants
interface ColorVariants {
  light: ColorValue
  dark: ColorValue
}

// Depth levels for semantic colors
type DepthLevel =
  | 'primary'
  | 'secondary'
  | 'tertiary'
  | 'quaternary'
  | 'quinary'

Color Utilities

import {
  parseOKLCH,
  formatOKLCH,
  validateColor,
  calculateContrastRatio,
} from '@pastel-palette/colors'

// Parse OKLCH color strings
const oklch = parseOKLCH('oklch(0.85 0.12 237)')
// { l: 0.85, c: 0.12, h: 237, a: 1 }

// Format OKLCH objects
const formatted = formatOKLCH({ l: 0.85, c: 0.12, h: 237 })
// "oklch(0.85 0.12 237)"

// Validate color formats
const validation = validateColor('oklch(0.85 0.12 237)')
// { valid: true, errors: [], warnings: [] }

// Calculate WCAG contrast ratios
const contrast = calculateContrastRatio(
  { r: 62, g: 59, b: 68 }, // Text color
  { r: 250, g: 248, b: 249 }, // Background color
)
// {
//   ratio: 12.5,
//   passes: { aa: true, aaa: true, largeTextAa: true, largeTextAaa: true }
// }

Color Categories

Regular Colors (colorSystem.regular)

All regular colors include light/dark variants:

• blue: Cotton candy blue
• pink: Sakura petal pink
• purple: Soft lavender
• green: Mint green
• orange: Peach orange
• yellow: Lemon yellow
• sky: Dreamy sky blue
• red: Soft coral red
• brown: Warm taupe
• gray: Neutral gray
• neutral: Ultra-light gray
• black: Soft black
• white: Off-white

Element Colors (colorSystem.element)

Semantic colors for UI elements with depth levels:

• text: Text colors (primary → quaternary)
• placeholder-text: Form placeholder text
• border: Border colors (primary, secondary)
• separator: Divider lines
• link: Interactive links
• disabled-control: Disabled form controls
• disabled-text: Disabled text

Background Colors (colorSystem.background)

System background colors with 5 depth levels:

• primary → secondary → tertiary → quaternary → quinary

Fill Colors (colorSystem.fill)

System fill colors with 4 depth levels:

• primary → secondary → tertiary → quaternary

Material Colors (colorSystem.material)

Translucent materials with varying opacity:

• ultra-thick: 93% opacity
• thick: 85% opacity
• medium: 72% opacity
• thin: 60% opacity
• ultra-thin: 45% opacity
• opaque: 100% opacity

Application Colors (colorSystem.application)

Brand colors for your application:

• accent: Main accent color
• primary: Primary brand color
• secondary: Secondary brand color

Advanced Usage

Custom Color Validation

import { validateColor } from '@pastel-palette/colors'

function validateThemeColors(colors: string[]) {
  return colors.map((color) => {
    const result = validateColor(color)
    if (!result.valid) {
      console.error(`Invalid color: ${color}`, result.errors)
    }
    if (result.warnings.length > 0) {
      console.warn(`Color warnings: ${color}`, result.warnings)
    }
    return result
  })
}

Accessibility Checking

import { calculateContrastRatio, parseRGB } from '@pastel-palette/colors'

function checkTextContrast(textColor: string, bgColor: string) {
  const text = parseRGB(textColor)
  const bg = parseRGB(bgColor)

  if (!text || !bg) {
    throw new Error('Invalid color format')
  }

  const contrast = calculateContrastRatio(text, bg)

  return {
    ratio: contrast.ratio.toFixed(2),
    meetsWCAG_AA: contrast.passes.aa,
    meetsWCAG_AAA: contrast.passes.aaa,
    recommendation: contrast.passes.aa
      ? 'Passes WCAG AA standards'
      : 'Consider increasing contrast',
  }
}

Exports

The package provides multiple export paths:

// Main exports
import { colorSystem, colorPalette } from '@pastel-palette/colors'

// Type definitions
import type { ColorValue, ColorVariants } from '@pastel-palette/colors/types'

// Utilities only
import { parseOKLCH, validateColor } from '@pastel-palette/colors/utils'

// Color palette info
import { colorPalette } from '@pastel-palette/colors/palette'

Development

Building

# Using the TypeScript compiler directly
npm run build:tsc

# Or using tsdown (if compatible)
npm run build

Type Checking

npx tsc --noEmit

Browser Support

• OKLCH Colors: Modern browsers (Chrome 111+, Firefox 113+, Safari 15.4+)
• sRGB Fallbacks: All browsers
• P3 Colors: Safari and modern displays with P3 support

License

MIT