31:T487,# CSS `contrast-color()` Proposal Explorer This proposal intends to **empower the [prefers-contrast](https://developer.mozilla.org/docs/Web/CSS/@media/prefers-contrast) media query** by creating a function that implements the options of the media query, is simple to get started with, but can scale to advanced needs of authors and users. **Your current contrast preference: `${contrast_preference == 'nopref' ? 'no preference' : contrast_preference}`** Your system contrast preference will be used in the following CSS function interactions when the Contrast Target is `auto`. You can change your system preference or emulate it from DevTools, and see the results and demos adjust to your setting. ## Getting Started Below is an interactive proposal interface built with [ColorJS](https://colorjs.io). Inside the section Function Options are a series of controls representing the various options being proposed for the syntax of the `contrast-color()` function. As the controls are changed by you, the Syntax Preview, contrast scores and usage samples will live update to demonstrate the usage and results of your customized `contrast-color()` function.32:Te4c,html`

`contrast-color()` found:

${best_contrast_match.lch}

Contrast Scores Preview

WCAG ${scores.wcag} Lstar ${parseInt(scores.lstar)} APCA ${parseInt(scores.apca)} Weber ${scores.weber} Michelson ${scores.michelson} DeltaPhi ${scores.deltaphi}

Normal Text (< 24px)

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

${AA_passfail.normal ? '✅':'🚫'} AA ${AAA_passfail.normal ? '✅':'🚫'} AAA

Large Text (> 24px)

Lorem ipsum dolor sit amet, consec tetur adipiscing elit.

${AA_passfail.large ? '✅':'🚫'} AA ${AAA_passfail.large ? '✅':'🚫'} AAA

Graphics, Icons and other UI Components

${AA_passfail.icon ? '✅':'🚫'} AA

`33:T10d2,### Explanations & Reasoning

What does the **CSSWG Syntax Definition** look like?

`contrast-color() = contrast-color(? / #{2,})`

What is the **base color**?

This is the color known ahead of time. An author is seeking a color to contrast against this color, sometimes for an appropriate color for the user given their preferences or match the targets given a color list or contrast target.

What is the reasoning for **foreground** and **background** options?

Some contrast algorithms (like APCA) require distinguishing the foreground and background colors in order to enhance the results. When omitted then background is assumed. It's a required input but may not be utilized by the target contrast algorithm.

What is a **color list** and why is it optional?

A color list provides a set of choices for the contrast-color() function to choose from.

When no colors are passed, the function will find the first passing color within hue of the base color.

When a color list is passed, the function will find the first passing color from the list.

When a color list is passed and the `max` contrast target is specified, the function will find the highest scoring color from the list.

This lets authors choose between an auto-assigned color, the first color from a predefined list of approved design system colors, or the maximum contrasting color from the list. As long as `auto` is the contrast target, a color will be picked based on the user's contrast preference.

What are the **algorithm** choices? What does **auto** mean when chosen?

The CSSWG is highly encouraging authors to take interest beyond WCAG 2.1 and the options in the explorer are the current set of algorithms being discussed.

Auto means let the browser choose the best tool it's equipped with. This gives up the choice to the browser, but if an author knows what they're doing or what they want out of the function, they can request a specific function. If that function is not available, the browser's provided auto default will be used.

What is **contrast target**? What does **auto** mean when chosen?

The contrast target follows the [prefers-contrast media query syntax](https://caniuse.com/mdn-css_at-rules_media_prefers-contrast) that's stable in all major browsers. **More**, **less** and **no-preference** are defined and known keywords that correlate with user preferences. Adaptive contrast is the default. It's critical for adaptive contrast that it's auto, as any explicit value that is passed in would mean authors need to write their own media queries to adapt to user preference.

**Max** has been added in this proposal, as a way for authors to express they just simply want black or white.

**Custom** has been added for authors who want to hand manage the user adapting color contrast results, like owning their own prefers-contrast media queries that adjust the functions parameters. It's also useful when the usage of the contrast function isn't just for text, like a hover effect or slightly subdued icon next to text. By choosing custom, authors must pass the ratio they target.

What is a **custom contrast target**?

This is only applicable when the contrast target of **custom** is selected in the explorer. The explorer then guides you through passing a relevant value to the chosen algorithm. The slider will adapt to the chosen algorithm.

If a color is not found that meets the requested custom target, black or white will be used.

34:T104c,### Use Cases 1. **Adaptive text colors for body copy**
For any Browser's default background color, find the nearest color based on the user's preference. ```css body { color: contrast-color(Canvas); } ``` 1. **User adapting text colors for links**
For any Browser's default background color, use blue, darkblue, lightblue, black or white to match the user's preference. ```css a { color: contrast-color(Canvas / blue, darkblue, lightblue); } ``` 1. **User adapting text colors from a design system for body copy**
Given a design token background color, choose one of 3 design system text color tokens to match the user's preference. ```css div { color: contrast-color(var(--surface-bg) / var(--text-1), var(--text-2), var(--text-3) ); } ``` 3. **::selection**
Easily create nice selections that follow the users system highlight color preference AND their contrast preference. I've passed max in this function so that either white or black are chosen, but if an author wanted they could omit that parameter and have text colors that follow the Highlight hue appropriately. ```css ::selection { color: contrast-color(Highlight / max); } ``` 5. **::cue and captions**
No worry about what the background color is, pick either white or black text for it browser. ```css ::cue { color: contrast-color(var(--cue-bg) / max); } ``` 1. **Colorful Tags / Chips**
Stay within the hue of the tag but find me an accessible color for this user browser. ```css .tag { background: var(--tag-bg); color: contrast-color(var(--tag-bg)); } .tag.info { --tag-bg: cyan } .tag.success { --tag-bg: green } .tag.warning { --tag-bg: yellow } .tag.error { --tag-bg: red } ``` 1. **Labelling color palettes**
Easily provide accessible text colors over the display of a color palette. ```css .swatch { --lightness: 5%; --swatch-bg: oklch(var(--lightness) 50 200); background: var(--swatch-bg); color: contrast-color(var(--swatch-bg) / max); } .swatch:nth-child(1) { --lightness: 5% } .swatch:nth-child(2) { --lightness: 15% } .swatch:nth-child(3) { --lightness: 25% } .swatch:nth-child(4) { --lightness: 35% } ... ``` 1. **Creating variants (svg icons, buttons)**
Let the browser pick text colors for you based on user contrast preferences. ```css .btn { --btn-bg: orange; background: var(--btn-bg); color: contrast-color(var(--btn-bg)); } .btn-svg { color: contrast-color(var(--btn-bg)); } .btn.variant1 { --btn-bg: hotpink } .btn.variant2 { --btn-bg: deeppink } .btn.variant3 { --btn-bg: indigo } .btn.variant4 { --btn-bg: rebeccapurple } ``` 1. scrollbar-color 1. accessible outline-color 1. Gradient 1. Personalization 1. Animations and transitions 1. Text on semi-transparent black over image 1. Accessible semi-transparent text 1. scroll-timeline hue rotate with accessible text 1. Advanced technical usage, explicitly providing parameters ```css :root { --contrast-target: 50; --hue: 250; --surface-1-L: 90; --surface-1-C: .015; --surface-1: oklch(var(--surface-1-L) var(--surface-1-C) var(--hue)); --text: contrast-color(var(--surface-1) / var(--contrast-target) apca); } html { background-color: var(--surface-1); color: var(--text); } @media (prefers-contrast: more) { html { --surface-1-L: 95; --contrast-target: 70; } } @media (prefers-contrast: less) { html { --surface-1-L: 85; --contrast-target: 30; } } @media (prefers-contrast: no-preference) and (prefers-color-scheme: dark) { :root { --hue: 265; --surface-1-L: 5; --surface-1-C: .05; } } @media (prefers-contrast: more) and (prefers-color-scheme: dark) { html { --surface-1-L: 2; } } @media (prefers-contrast: less) and (prefers-color-scheme: dark) { html { --surface-1-L: 20; } } ```35:T755,collapsedCSS` .results { display: grid; grid-template-columns: 1fr 1fr; align-items: start; gap: 4ch; margin-block-start: 8ch; } .results > div:first-child { grid-column: -1/1; } .preview { display: flex; flex-direction: column; align-items: center; justify-content: center; text-align: center; gap: .5ch; padding: 5ch; box-shadow: inset 0 0 0 1px #ccc; font-family: system-ui, sans-serif; font-size: 1.25rem; } .preview > p { max-inline-size: 30ch; text-align: left; } .example-function { font-family: ui-monospace, monospace; background: hsl(0 0% 20%); color: hsl(0 0% 100%); padding: 1ch 2ch; border-radius: 5px; } .swatches { display: grid; gap: 1ch; } .swatch { display: flex; align-items: center; gap: 1ch; font-family: ui-monospace, monospace; color: black; } .sample { block-size: 2.5ch; aspect-ratio: 1; border-radius: 50%; box-shadow: inset 0 0 0 1px #ccc; } details > p { margin-block-start: .25ch; margin-inline-start: 2.5ch; } summary { cursor: pointer; } summary > strong { color: LinkText; } h1 > code { font-weight: bold; } .small-text { padding: 20px 30px; font-family: system-ui, sans-serif; box-shadow: inset 0 0 0 1px #ccc; margin-block-end: 0; } .large-text { font-size: 24px; padding: 20px 30px; font-family: system-ui, sans-serif; box-shadow: inset 0 0 0 1px #ccc; margin-block-end: 0; } .preview-icon { inline-size: 64px; aspect-ratio: 1; border-radius: 50%; display: inline-flex; align-items: center; justify-content: center; box-shadow: inset 0 0 0 1px #ccc; margin-inline-end: 1ch; } .preview-icon svg { max-inline-size: 50%; } .wcag-results { margin-block-start: 5px; display: flex; gap: 2ch; align-items: center; font-family: system-ui, sans-serif; } .wg-syntax { background: #eee; padding: 1ch 2ch; } `36:T5f9,ColorContrast = options => { let base = new Color(options.base) let found = {result: null, darker: null, lighter: null} let toBlack = base.steps(new Color('black'), {maxDeltaE: 1}) let toWhite = base.steps(new Color('white'), {maxDeltaE: 1}) let checkRatio = c => { let contrast = options.algo === 'APCA' && options.role === 'foreground' ? new Color(c).contrast(base, options.algo) : new Color(base).contrast(c, options.algo) return Math.abs(contrast) >= options.target // Math.abs is for APCA } if (!options.colors) { found.darker = toBlack.find(checkRatio) found.lighter = toWhite.find(checkRatio) found.result = found.darker || found.lighter } else { found.result = options.colors.split(',') .map(a => a.trim()) .map(color => new Color(color)) .find(checkRatio) } if (!found.result) { let darkest = toBlack.at(-1) let lightest = toWhite.at(-1) let darkestScore = darkest.contrast(base, 'Lstar') let lightestScore = lightest.contrast(base, 'Lstar') found.result = darkestScore > lightestScore ? darkest : lightest } return { hex: found.result.to('srgb').toString({format: "hex"}), lch: found.result.to('lch').toString(), oklch: found.result.to('oklch').toString(), lab: found.result.to('lab').toString(), oklab: found.result.to('oklab').toString(), hsl: found.result.to('hsl').toString(), rgb: found.result.to('srgb').toString(), p3: found.result.to('p3').toString(), } }37:T633,function colorPicker(defaultValue) { const isHex = defaultValue.indexOf('#') === 0 const container = html` ${styles}

Base color (required)

`; const picker = container.querySelector("#picker") const label = container.querySelector("#label") const setValue = colorStr => { let colorPicked = new Color(colorStr) let color = isHex ? colorPicked.to('srgb').toString({format: 'hex'}) : colorPicked.toString() label.innerHTML = color container.value = color container.dispatchEvent(new window.Event("input")) } setValue(defaultValue) const setupPickr = () => { let pickr = new Pickr({ el: picker, default: new Color(defaultValue).to('hsl').toString(), comparison: false, components: { preview: true, opacity: true, hue: true, interaction: { hex: true, rgba: true, hsla: true, hsva: true, cmyk: false, input: true, clear: false, save: false } } }) pickr.on('change', c => setValue(c.toHSLA().toString())) } const interval = setInterval(() => { if (document.body.contains(container)) { clearInterval(interval) setupPickr() } }, 100) return container }38:[] 2f:{"title":"CSS contrast-color() Proposal Explorer","cells":[{"id":884,"value":"$31","pinned":false,"hidden":false,"mode":"md"},{"id":1190,"value":"```css\n/* updates as you set options */\n.syntax-preview {\n ${fg_or_bg === 'background' ? 'background' : 'color'}: ${basecolor};\n ${fg_or_bg === 'background' ? 'color' : 'background'}: contrast-color(${fg_or_bg === 'background'?'':'foreground '}${basecolor}${contrast_target !== 'auto' || contrast_algorithm !== 'auto' ? ' / ' : ''}${contrast_target === 'custom'?custom_target:contrast_target==='auto'?'':contrast_target}${contrast_algorithm !== 'auto' ? (contrast_target !== 'auto' ? ' ':'')+contrast_algorithm.toLowerCase() : ''}${color_list && ' ' + color_list});\n}\n```","pinned":false,"hidden":false,"mode":"md"},{"id":1125,"value":"## Function Options","pinned":false,"hidden":false,"mode":"md"},{"id":1666,"value":"viewof basecolor = Inputs.text({label: \"Base color (required)\", placeholder: \"any CSS color\", value: \"deeppink\"})","pinned":false,"hidden":false,"mode":"ojs"},{"id":553,"value":"viewof fg_or_bg = Inputs.radio([\"background\", \"foreground\"], {label: \"Base color role\", value: \"background\"})","pinned":false,"hidden":false,"mode":"ojs"},{"id":726,"value":"viewof color_list = Inputs.text({label: \"Color List\", placeholder: \"hotpink, #C55, hsl(200 50% 50%), ...\"})","pinned":false,"hidden":false,"mode":"ojs"},{"id":461,"value":"viewof contrast_algorithm = Inputs.radio([\"auto\", \"WCAG21\", \"APCA\", \"Lstar\", \"Weber\", \"Michelson\", \"DeltaPhi\"], {label: \"Contrast Algorithm\", value: \"auto\"})","pinned":false,"hidden":false,"mode":"ojs"},{"id":497,"value":"viewof contrast_target = Inputs.radio([\"auto\", \"max\", \"more\", \"less\", \"custom\"], {label: \"Contrast Target\", value: \"auto\"})","pinned":false,"hidden":false,"mode":"ojs"},{"id":1349,"value":"viewof custom_target = {\n // todo: get more official min/max\n // todo: normalize things to range 0-100\n let algoRanges = {\n WCAG21: {range: [0,21], step: .1, value: 4.5},\n Lstar: {range: [0,100], step: 1, value: 50},\n APCA: {range: [0,110], step: 1, value: 70},\n Weber: {range: [0,10], step: .1, value: 5},\n Michelson: {range: [0,1], step: .01, value: .5},\n DeltaPhi: {range: [0,100], step: 1, value: 58},\n }\n \n let algo = algoRanges[contrast_algo_mapped]\n \n return Inputs.range(algo.range, {\n label: \"Custom Target\", \n value: algo_map[contrast_algo_mapped][contrast_target] || algo.value, \n step: algo.step, \n disabled: contrast_target !== \"custom\"\n })\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":0,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":1415,"value":"---","pinned":false,"hidden":false,"mode":"md"},{"id":854,"value":"$33","pinned":false,"hidden":false,"mode":"md"},{"id":956,"value":"------","pinned":false,"hidden":false,"mode":"md"},{"id":1104,"value":"$34","pinned":false,"hidden":false,"mode":"md"},{"id":558,"value":"**To Do:**\n1. Add list of use cases and `contrast-color()` syntax previews\n1. Add opacity handling for contrast\n1. Add delta-phi and bpca contrast algorithms \n1. Normalize percentages for contrast as optional style of target score\n2. Explain how animation and transitions work\n3. Consider CSS property for setting the default contrast algorithm (allow a user to control it, not just the browser)\n4. Summarize use cases into intro, make them in page links","pinned":false,"hidden":false,"mode":"md"},{"id":1093,"value":"------","pinned":false,"hidden":false,"mode":"md"},{"id":1090,"value":"## Document Functions & Styles\nBelow are the blocks that support this notebook. Many of them are showing you right now the dynamic value they play in the calculation of this document.\n\n### CSS","pinned":false,"hidden":false,"mode":"md"},{"id":10,"value":"$35","pinned":false,"hidden":false,"mode":"ojs"},{"id":556,"value":"### JS","pinned":false,"hidden":false,"mode":"md"},{"id":1136,"value":"$36","pinned":false,"hidden":false,"mode":"ojs"},{"id":82,"value":"best_contrast_match = ColorContrast({\n base: basecolor,\n role: fg_or_bg,\n colors: color_list,\n algo: contrast_algo_mapped,\n target: target_ratio,\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":572,"value":"target_ratio = {\n let ratio\n \n if (contrast_target === 'custom')\n ratio = custom_target\n else if(contrast_target === 'auto') {\n ratio = algo_map[contrast_algo_mapped][contrast_preference]\n }\n else\n ratio = algo_map[contrast_algo_mapped][contrast_target]\n\n return ratio\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":809,"value":"contrast_algo_mapped = {\n return contrast_algorithm === 'auto'\n ? 'Lstar'\n : contrast_algorithm\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":675,"value":"algo_map = {\n return {\n WCAG21: {nopref: 4.5, more: 7, less: 3},\n Lstar: {nopref: 50, more: 60, less: 40},\n APCA: {nopref: 75, more: 90, less: 60},\n Weber: {nopref: 18, more: 91, less: 7},\n Michelson: {nopref: .9, more: 1, less: .7},\n DeltaPhi: {nopref: 65, more: 80, less: 50},\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":431,"value":"contrast_preference = {\n let less = window.matchMedia('(prefers-contrast: less)').matches ? 'less' : false\n let more = window.matchMedia('(prefers-contrast: more)').matches ? 'more' : false\n let nopref = window.matchMedia('(prefers-contrast: no-preference)').matches ? 'nopref' : false\n\n return less || more || nopref\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":477,"value":"theme_preference = {\n let dark = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : false\n let light = window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : false\n let nopref = window.matchMedia('(prefers-color-scheme: no-preference)').matches ? 'no preference' : false\n\n return dark || light || nopref\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":425,"value":"scores = {\n let base = new Color(basecolor)\n let found = new Color(best_contrast_match.lab)\n \n return {\n wcag: base.contrast(found, 'WCAG21').toFixed(2),\n lstar: base.contrast(found, 'Lstar').toFixed(2),\n weber: base.contrast(found, 'Weber').toFixed(2),\n michelson: base.contrast(found, 'Michelson').toFixed(2) * 100,\n apca: fg_or_bg === 'background'\n ? base.contrast(found, 'APCA').toFixed(2)\n : found.contrast(base, 'APCA').toFixed(2),\n deltaphi: base.contrast(found, 'DeltaPhi').toFixed(),\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":987,"value":"AA_passfail = {\n return {\n normal: scores.wcag > 4.5,\n large: scores.wcag > 3,\n icon: scores.wcag > 3,\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":991,"value":"AAA_passfail = {\n return {\n normal: scores.wcag > 7,\n large: scores.wcag > 4.5,\n // icon: scores.wcag > 3,\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1243,"value":"$37","pinned":false,"hidden":false,"mode":"ojs"},{"id":65,"value":"Color = (await import('https://colorjs.io/dist/color.js')).default","pinned":false,"hidden":false,"mode":"ojs"},{"id":21,"value":"css = tagWithOptions(({ transform }) => (...args) => {\n const source = interpolate(...args);\n const style = html`\n`","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W38","stdlib":"1","titling":"auto"}

contrast-color() found:

Contrast Scores Preview

Normal Text (< 24px)

Large Text (> 24px)

Graphics, Icons and other UI Components

`contrast-color()` found: