Доступность (WCAG)

Подбор цвета текста

bestGradientTextColor(colors, options?)

Возвращает '#000000' или '#ffffff' — в зависимости от того, что даёт лучший минимальный контраст по всем точкам градиента.

import { bestGradientTextColor } from 'css-magic-gradient'

// Двухцветный градиент (обратная совместимость)
bestGradientTextColor('#1a1a2e', '#e94560')
// → '#ffffff'

// Многоточечный градиент
bestGradientTextColor(['#1a1a2e', '#c0357a', '#e94560'])
// → '#ffffff'

// Детальный результат с оценками по каждому цвету
const detail = bestGradientTextColor(['#1a1a2e', '#e94560'], { detailed: true })
// → { recommended: '#ffffff', black: { contrast: 1.8, wcag: 'fail' }, white: { contrast: 9.3, wcag: 'AAA' } }

Коэффициент контрастности

gradientContrastRatio(textColor, colors)

Возвращает минимальный коэффициент контрастности WCAG цвета текста относительно градиента. Выбирает 11 равномерно распределённых точек вдоль градиента.

import { gradientContrastRatio } from 'css-magic-gradient'

// Два цвета (обратная совместимость)
gradientContrastRatio('#ffffff', '#1a1a2e', '#e94560')
// → минимальный коэффициент по всем выбранным точкам

// Массив точек
gradientContrastRatio('#ffffff', ['#1a1a2e', '#c0357a', '#e94560'])

WCAG-отчёт

gradientWcagLevel(textColor, colors)

Возвращает подробный GradientWcagReport с наихудшим уровнем WCAG, минимальным контрастом и позициями, не проходящими порог AA.

import { gradientWcagLevel } from 'css-magic-gradient'

const report = gradientWcagLevel('#ffffff', '#1a1a2e', '#e94560')
// → {
//     level: 'AAA',
//     minContrast: 8.4,
//     problematicStops: []   // позиции (0–1), где контраст < 4.5
//   }

// Градиент со слабой средней точкой:
const report2 = gradientWcagLevel('#ffffff', ['#ffffff', '#aaaaaa', '#3498db'])
// → { level: 'fail', minContrast: 1.07, problematicStops: [0, 0.09, 0.18, …] }

GradientWcagReport

level

WcagLevel

Наихудший уровень WCAG среди всех выбранных точек.

minContrast

number

Минимальный коэффициент контрастности вдоль градиента.

problematicStops

number[]

Дробные позиции (0–1), где контраст < 4.5.

Доступный градиент

createAccessibleGradient(baseColor, textColor, options?)

Автоматически подстраивает точки градиента, пока textColor не достигнет целевого уровня WCAG.

import { createAccessibleGradient } from 'css-magic-gradient'

// По умолчанию: подстраивает светлоту шагами по 5%, пока не достигнут AA
createAccessibleGradient('#3498db', '#ffffff', {
  targetLevel: 'AA',
})

// Подстраивать насыщенность вместо этого
createAccessibleGradient('#3498db', '#ffffff', {
  targetLevel: 'AAA',
  adjustmentStrategy: 'saturation',
})

// Подстраивать и светлоту, и насыщенность
createAccessibleGradient('#c0357a', '#000000', {
  adjustmentStrategy: 'both',
  direction: 'to right',
})

AccessibleGradientOptions

direction

string · по умолчанию: 'to bottom'

Ключевое слово CSS-направления.

angle

number

Угол в градусах.

targetLevel

'AAA' | 'AA' | 'AA-large' · по умолчанию: 'AA'

Минимальный уровень контраста WCAG.

adjustmentStrategy

'lightness' | 'saturation' | 'both' · по умолчанию: 'lightness'

Как подстраиваются точки цвета.

interpolation

ColorInterpolation

Интерполяция CSS Color Level 4.

repeating

boolean · по умолчанию: false

Использовать repeating-linear-gradient.

Реэкспортировано из color-value-tools

Функции gradient* выше — это собственные, градиент-осведомлённые утилиты WCAG этого пакета. color-value-tools (единственная runtime-зависимость пакета) уже поставляет одноцветные аналоги — css-magic-gradient реэкспортирует их напрямую, так что потребителю не нужно ставить color-value-tools отдельно только ради проверки одной пары фон/текст.

import { bestTextColor, wcagLevel, contrastRatio, isDark } from 'css-magic-gradient'

bestTextColor(background)

(background: string) => '#000000' | '#ffffff'

Одноцветный аналог bestGradientTextColor — выбирает чёрный или белый для лучшего контраста относительно одного фонового цвета, а не всего набора точек градиента.

bestTextColor('#1a1a2e') // → '#ffffff'

contrastRatio(a, b)

(a: string, b: string) => number

Коэффициент контрастности WCAG между двумя плоскими цветами.

contrastRatio('#ffffff', '#1a1a2e') // → 15.8

wcagLevel(foreground, background)

(foreground: string, background: string) => WcagLevel

Уровень WCAG ('AAA' | 'AA' | 'AA-large' | 'fail') для одной пары фон/текст.

wcagLevel('#ffffff', '#1a1a2e') // → 'AAA'

isDark(color, threshold?)

(color: string, threshold?: number) => boolean

Является ли цвет перцептивно тёмным. threshold по умолчанию 0.5.

isDark('#1a1a2e') // → true