@vapor-ui/color-generator/dist/index.d.ts

접근성을 고려한 대비비 기반 색상 팔레트 생성 라이브러리

type ThemeType = 'light' | 'dark' | 'base';
type TokenType = 'primitive' | 'semantic' | 'component-specific';
interface OklchColor {
    mode: 'oklch';
    l: number;
    c: number;
    h?: number;
}
interface ColorToken {
    name: string;
    hex: string;
    oklch: string;
    deltaE?: number;
    codeSyntax: string;
}
interface Tokens {
    [tokenName: string]: ColorToken | string;
}
interface ScaleInfo {
    backgroundScale: string;
    foregroundScale: string;
    alternativeScale: string;
}
interface TokenContainer {
    tokens: Tokens;
    metadata: {
        type: TokenType;
        theme: ThemeType;
    };
}
interface ColorPaletteResult {
    base?: TokenContainer;
    light: TokenContainer;
    dark: TokenContainer;
}
interface SemanticTokensResult {
    semantic: {
        light: TokenContainer;
        dark: TokenContainer;
    };
    componentSpecific: {
        light: TokenContainer;
        dark: TokenContainer;
    };
}

declare const BASE_COLORS: {
    readonly white: {
        readonly name: "color-white";
        readonly hex: "#FFFFFF";
        readonly oklch: "oklch(1 0 0)";
        readonly codeSyntax: "vapor-color-white";
    };
    readonly black: {
        readonly name: "color-black";
        readonly hex: "#000000";
        readonly oklch: "oklch(0 0 0)";
        readonly codeSyntax: "vapor-color-black";
    };
};
declare const DEFAULT_PRIMITIVE_COLORS: {
    readonly red: "#F5535E";
    readonly pink: "#F26394";
    readonly grape: "#CC5DE8";
    readonly violet: "#8662F3";
    readonly blue: "#448EFE";
    readonly cyan: "#1EBAD2";
    readonly green: "#04A37E";
    readonly lime: "#8FD327";
    readonly yellow: "#FFC107";
    readonly orange: "#ED670C";
};

declare const DEFAULT_MAIN_BACKGROUND_LIGHTNESS: {
    readonly light: 100;
    readonly dark: 14;
};
declare const DEFAULT_CONTRAST_RATIOS: {
    readonly '050': 1.07;
    readonly '100': 1.3;
    readonly '200': 1.7;
    readonly '300': 2.5;
    readonly '400': 3;
    readonly '500': 4.5;
    readonly '600': 6.5;
    readonly '700': 8.5;
    readonly '800': 11.5;
    readonly '900': 15;
};
declare const ADAPTIVE_COLOR_GENERATION: {
    readonly LIGHTNESS_THRESHOLD: 0.5;
    readonly DARK_LIGHTNESS_FACTOR: 0.55;
    readonly LIGHT_LIGHTNESS_FACTOR: 0.85;
    readonly CHROMA_REDUCTION_FACTOR: 0.85;
};
declare const BUTTON_FOREGROUND_LIGHTNESS_THRESHOLD = 0.65;

type Colors = Record<string, string>;
type ContrastRatios = Record<keyof typeof DEFAULT_CONTRAST_RATIOS, number>;
type BackgroundLightness = Record<keyof typeof DEFAULT_MAIN_BACKGROUND_LIGHTNESS, number>;
type Background = {
    name: string;
    color: string;
    lightness: BackgroundLightness;
};
interface ColorGeneratorConfig {
    colors?: Colors;
    contrastRatios?: ContrastRatios;
    background?: Background;
}
interface BrandColorGeneratorConfig extends ColorGeneratorConfig {
    colors: {
        [colorName: string]: string;
    };
}

/**
 * 시스템 컬러 팔레트를 생성합니다.
 * Primitive 토큰들을 포함한 일관된 토큰 컨테이너 형태로 반환합니다.
 *
 * @param config - 색상 생성기 설정
 * @returns 기본, 라이트, 다크 테마의 토큰 컨테이너
 *
 * @example
 * generateSystemColorPalette()
 * // returns: {
 * //   base: { tokens: { "color-white": {...}, "color-black": {...} }, metadata: {...} },
 * //   light: { tokens: { "color-blue-050": {...}, "color-background-canvas": {...} }, metadata: {...} },
 * //   dark: { tokens: { ... }, metadata: {...} }
 * // }
 */
declare function generateSystemColorPalette(config?: ColorGeneratorConfig): ColorPaletteResult;

/**
 * 브랜드 컬러 팔레트를 생성합니다.
 * 사용자 정의 브랜드 컬러를 기반으로 Primitive 토큰들을 생성합니다.
 *
 * @param config - 브랜드 컬러 설정
 * @returns 라이트, 다크 테마의 토큰 컨테이너 (base 제외)
 *
 * @example
 * generateBrandColorPalette({ colors: { myBlue: '#448EFE' } })
 * // returns: {
 * //   light: { tokens: { "color-myBlue-050": {...}, "color-myBlue-100": {...} }, metadata: {...} },
 * //   dark: { tokens: { ... }, metadata: {...} }
 * // }
 */
type BrandColorPalette = Omit<ColorPaletteResult, 'base'>;
declare function generateBrandColorPalette(config: BrandColorGeneratorConfig): BrandColorPalette;

interface SemanticMappingConfig {
    primary: {
        name: string;
        color: string;
    };
    secondary?: {
        name: string;
        color: string;
    };
    success?: {
        name: string;
        color: string;
    };
    warning?: {
        name: string;
        color: string;
    };
    error?: {
        name: string;
        color: string;
    };
    background: Background;
}
/**
 * 시맨틱 토큰을 생성합니다.
 * 브랜드 컬러를 기반으로 semantic과 component-specific 토큰을 분리하여 생성합니다.
 *
 * @param mappingConfig - 시맨틱 역할과 브랜드 컬러 매핑 설정
 * @returns semantic과 componentSpecific으로 분리된 토큰 컨테이너
 */
declare function getSemanticDependentTokens(mappingConfig: SemanticMappingConfig): SemanticTokensResult;

/**
 * 색상의 LCH Lightness 값을 반환합니다.
 *
 * @param colorHex - HEX 색상 값
 * @returns 0-100 범위의 정수 lightness 값 또는 null
 */
declare const getColorLightness: (colorHex: string) => number | null;

export { ADAPTIVE_COLOR_GENERATION, BASE_COLORS, BUTTON_FOREGROUND_LIGHTNESS_THRESHOLD, type Background, type BackgroundLightness, type BrandColorGeneratorConfig, type ColorGeneratorConfig, type ColorPaletteResult, type ColorToken, type Colors, type ContrastRatios, DEFAULT_CONTRAST_RATIOS, DEFAULT_MAIN_BACKGROUND_LIGHTNESS, DEFAULT_PRIMITIVE_COLORS, type OklchColor, type ScaleInfo, type SemanticMappingConfig, type SemanticTokensResult, type ThemeType, type TokenContainer, type TokenType, type Tokens, generateBrandColorPalette, generateSystemColorPalette, getColorLightness, getSemanticDependentTokens };