Core Library API

@colorx/core is a standalone TypeScript library with zero dependencies. It can be used independently of the React app.

Installation

# From the monorepo
import { generateTheme } from "@colorx/core";

Main API

generateTheme(hex: string): ThemeOutput

Generate a complete light and dark theme from a single hex color.

const output = generateTheme("#6366f1");

output.input;          // "#6366f1"
output.light;          // ThemeColors (15 tokens)
output.dark;           // ThemeColors (15 tokens)
output.contrast.light; // Record<string, ContrastResult>
output.contrast.dark;  // Record<string, ContrastResult>
output.css;            // Ready-to-use CSS custom properties

checkAPCA(fgHex: string, bgHex: string): APCAResult

Calculate APCA Lc contrast between two colors.

const result = checkAPCA("#1a1a1a", "#ffffff");

result.Lc;      // ~107 (Lightness Contrast value)
result.passes;  // true
result.level;   // "body" | "heading" | "non-text" | "fail"

APCA thresholds:

• Body text (16px): |Lc| >= 60
• Headings (24px / 18px bold): |Lc| >= 45
• Non-text / large UI: |Lc| >= 30

simulateThemeCVD(theme: ThemeColors, type: CVDType): ThemeColors

Simulate how a theme appears to someone with a color vision deficiency.

// Color Vision Deficiency (CVD) -- the technical term for color blindness
type CVDType = "deuteranopia" | "protanopia" | "tritanopia" | "achromatopsia";

const simulated = simulateThemeCVD(output.light, "deuteranopia");

Utility Exports

// Color conversion
hexToRgb(hex: string): RGB
rgbToHex(rgb: RGB): string
rgbToHsl(rgb: RGB): HSL
hslToRgb(hsl: HSL): RGB

// WCAG 2.1 contrast
contrastRatio(color1: string, color2: string): number
checkContrast(fg: string, bg: string): ContrastResult

// Color manipulation
adjustLightness(hex: string, targetL: number): string
mixColors(hex1: string, hex2: string, weight: number): string
ensureContrast(fg: string, bg: string, minRatio: number, mode: "lighten" | "darken"): string

// APCA
calcAPCA(fgHex: string, bgHex: string): number

// CVD simulation
simulateCVD(hex: string, type: CVDType): string

Types

interface ThemeColors {
  background, surface, surfaceAlt, primary, primaryHover, primaryText,
  text, textSecondary, textMuted, border, borderLight,
  success, warning, error, info: string;
}

interface ContrastResult {
  ratio: number;
  aa: boolean;      // >= 4.5:1
  aaLarge: boolean;  // >= 3:1
  aaa: boolean;      // >= 7:1
  aaaLarge: boolean;  // >= 4.5:1
}

interface APCAResult {
  Lc: number;
  passes: boolean;
  level: "body" | "heading" | "non-text" | "fail";
}