API Reference

import { generatePalette } from '@sveltopia/colors';

// Returns a single-mode LightPalette — call once per mode
const light = generatePalette({
  brandColors: ['#FF4F00', '#1A1A1A'],
  // Optional: 'light' (default) | 'dark'
  mode: 'light',
  // Optional: override the auto-detected tuning profile
  tuningProfile: undefined
});

// light.scales['orange'][9] → '#FF4F00' (or close to it)
// light.meta.anchoredSlots → ['orange']
// light.meta.tuningProfile → { hueShift, chromaMultiplier, ... }

// Generate dark mode with the same inputs
const dark = generatePalette({
  brandColors: ['#FF4F00', '#1A1A1A'],
  mode: 'dark'
});

import { analyzeBrandColors } from '@sveltopia/colors';

const profile = analyzeBrandColors(['#FF4F00']);

// profile.hueShift → average hue offset from baseline
// profile.chromaMultiplier → brand chroma relative to baseline
// profile.anchors → { '#FF4F00': { slot: 'orange', step: 9 } }

import { exportCSS } from '@sveltopia/colors';

const css = exportCSS(palette, {
  lightSelector: ':root',              // default
  darkSelector: '.dark, .dark-theme',  // default
  includeAlpha: true,             // default
  includeP3: true,                // default
  includeSemantic: true,          // default
  scales: undefined,              // all scales, or ['orange', 'blue']
  prefix: '',                     // CSS variable prefix
  mode: 'both'                    // 'light' | 'dark' | 'both'
});

import { exportJSON } from '@sveltopia/colors';

const data = exportJSON(palette, {
  scales: undefined,              // all scales, or specific ones
  includeAlpha: true,
  includeP3: true,
  includeSemantic: true
});

// data.light['orange']['9'] → { hex: '#FF4F00', oklch: '...', p3: '...' }

import { exportTailwindV4CSS } from '@sveltopia/colors';

const css = exportTailwindV4CSS(palette, {
  includeSemanticRoles: true,     // primary, secondary, tertiary
  darkSelector: '.dark',
  lightSelector: ':root',
  includeThemeBlock: true         // @theme {} registration
});

import { exportTailwind } from '@sveltopia/colors';

const js = exportTailwind(palette, {
  scale: '50-950',          // '50-950' | '1-12'
  darkMode: 'class',        // 'class' | 'media'
  includeAlpha: false        // include alpha variants
});

import { exportShadcn } from '@sveltopia/colors';

const css = exportShadcn(palette, {
  radius: '0.625rem',
  neutralHue: 'slate',
  destructiveHue: 'red',
  includeCharts: true,
  includeSidebar: true,
  includeThemeBlock: true,
  includeThemeInlineBlock: true,
  lightSelector: ':root',
  darkSelector: '.dark'
});

import { exportRadix } from '@sveltopia/colors';

const js = exportRadix(palette, {
  format: 'esm',         // 'esm' | 'cjs'
  includeAlpha: true,
  includeP3: true
});

import { exportPanda } from '@sveltopia/colors';

const brandColorInfo = [
  { hex: '#FF4F00', hue: 'orange', anchorStep: 9, isCustomRow: false }
];

const ts = exportPanda(palette, brandColorInfo, {
  includeSemantic: true   // include semantic tokens (default: true)
});

import { calculateAPCA } from '@sveltopia/colors';

const contrast = calculateAPCA('#1A1A1A', '#FFFFFF');
// → ~106 (very high contrast)

import { validatePaletteContrast } from '@sveltopia/colors';

const report = validatePaletteContrast(palette, {
  hues: undefined,        // all hues, or ['orange', 'blue']
  errorsOnly: false       // true to suppress warnings
});

// report.passed → boolean
// report.totalChecks → number
// report.passedChecks → number
// report.issues → [{ hue, mode, textStep, bgStep, expected, actual, severity }]

interface OklchColor {
  l: number;      // Lightness (0–1)
  c: number;      // Chroma (0–~0.4)
  h: number;      // Hue (0–360)
  alpha?: number;
}

interface Scale {
  1: string;  // lightest (backgrounds)
  2: string;
  3: string;
  4: string;
  5: string;
  6: string;
  7: string;
  8: string;
  9: string;  // primary solid (brand anchor)
  10: string;
  11: string;
  12: string; // darkest (text)
}

interface Palette {
  light: Record<string, Scale>;
  dark: Record<string, Scale>;
  _meta: {
    tuningProfile: TuningProfile;
    inputColors: string[];
    generatedAt: string;
  };
}

interface TuningProfile {
  hueShift: number;
  chromaMultiplier: number;
  lightnessShift: number;
  anchors: Record<string, AnchorInfo>;
  customRows?: CustomRowInfo[];
}

interface ContrastReport {
  passed: boolean;
  totalChecks: number;
  passedChecks: number;
  issues: ContrastIssue[];
}