feat(clerk-js): Update color logic utils to support CSS variable usage #6187

alexcarpenter · 2025-06-24T16:20:18Z

🎨 Add Modern CSS Color-Mix Utilities

Resolves USER-2201

Overview

This PR introduces modern CSS color manipulation utilities that leverage native browser features like color-mix() and relative color syntax when supported, while maintaining backward compatibility with legacy HSLA-based color manipulation.

What's New

Progressive Enhancement Architecture

CSS Support Detection: Detects browser support for modern CSS color features
Graceful Fallback: Uses modern CSS when available, falls back to legacy JavaScript manipulation
Consistent API: Same function signatures work regardless of browser support

Modern CSS Features

color-mix() Support: Leverages native CSS color mixing
Relative Color Syntax: Uses hsl(from color h s l) syntax when supported
Alpha Transparency: Modern color-mix(in srgb, transparent, color X%) for opacity

CSS Variable Support

This enhancement enables CSS custom property support within the appearance.variables object:

appearance: {
  variables: {
    colorPrimary: 'var(--brand-color)',
    colorDanger: 'var(--error-color, #ef4444)',
    colorNeutral: 'var(--neutral, black)'
  }
}

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- Introduced modern CSS color manipulation utilities with progressive enhancement and automatic fallback for older browsers.
- Added support for CSS variables in appearance customization, enabling advanced theming options.
- Enhanced Stripe appearance customization by dynamically resolving computed CSS styles.
Bug Fixes
- Improved compatibility and fallback handling for color customization in environments lacking modern CSS support.
Refactor
- Updated styling across components to use CSS calc() for negative spacing, ensuring more robust and readable CSS.
Documentation
- Added comprehensive documentation for the new color utilities.
Tests
- Introduced extensive test coverage for color utilities, CSS variable handling, and browser feature detection.
Chores
- Cleaned up obsolete utilities and tests, consolidating and modernizing color-related code.

changeset-bot · 2025-06-24T16:20:23Z

🦋 Changeset detected

Latest commit: a84db2d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@clerk/clerk-js	Minor
@clerk/chrome-extension	Patch
@clerk/clerk-expo	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-06-24T16:20:23Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 7, 2025 5:35pm

- Added custom appearance variables in app.ts for improved styling. - Introduced a new CSS variable for brand color in template.html. - Removed unused simpleColorMix function from color utilities in utils.ts.

alexcarpenter · 2025-06-25T14:54:09Z

!snapshot

clerk-cookie · 2025-06-25T14:56:22Z

Hey @alexcarpenter - the snapshot version command generated the following package versions:

Package	Version
@clerk/clerk-expo	2.14.0-snapshot.v20250625145444

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/clerk-expo

npm i @clerk/clerk-expo@2.14.0-snapshot.v20250625145444 --save-exact

…hub.com:clerk/javascript into alexcarpenter/user-2201-add-color-mix-utilities

alexcarpenter · 2025-07-03T14:24:11Z

!snapshot

clerk-cookie · 2025-07-03T14:26:34Z

Hey @alexcarpenter - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.1.5-snapshot.v20250703142444
@clerk/astro	2.10.2-snapshot.v20250703142444
@clerk/backend	2.4.0-snapshot.v20250703142444
@clerk/chrome-extension	2.5.3-snapshot.v20250703142444
@clerk/clerk-js	5.70.0-snapshot.v20250703142444
@clerk/elements	0.23.37-snapshot.v20250703142444
@clerk/clerk-expo	2.14.2-snapshot.v20250703142444
@clerk/expo-passkeys	0.3.14-snapshot.v20250703142444
@clerk/express	1.7.4-snapshot.v20250703142444
@clerk/fastify	2.4.4-snapshot.v20250703142444
@clerk/localizations	3.17.3-snapshot.v20250703142444
@clerk/nextjs	6.23.3-snapshot.v20250703142444
@clerk/nuxt	1.7.5-snapshot.v20250703142444
@clerk/clerk-react	5.32.4-snapshot.v20250703142444
@clerk/react-router	1.6.4-snapshot.v20250703142444
@clerk/remix	4.8.5-snapshot.v20250703142444
@clerk/shared	3.10.2-snapshot.v20250703142444
@clerk/tanstack-react-start	0.18.3-snapshot.v20250703142444
@clerk/testing	1.9.2-snapshot.v20250703142444
@clerk/themes	2.2.54-snapshot.v20250703142444
@clerk/types	4.63.0-snapshot.v20250703142444
@clerk/vue	1.8.12-snapshot.v20250703142444

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/agent-toolkit@0.1.5-snapshot.v20250703142444 --save-exact

@clerk/astro

npm i @clerk/astro@2.10.2-snapshot.v20250703142444 --save-exact

@clerk/backend

npm i @clerk/backend@2.4.0-snapshot.v20250703142444 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@2.5.3-snapshot.v20250703142444 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@5.70.0-snapshot.v20250703142444 --save-exact

@clerk/elements

npm i @clerk/elements@0.23.37-snapshot.v20250703142444 --save-exact

@clerk/clerk-expo

npm i @clerk/clerk-expo@2.14.2-snapshot.v20250703142444 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@0.3.14-snapshot.v20250703142444 --save-exact

@clerk/express

npm i @clerk/express@1.7.4-snapshot.v20250703142444 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.4.4-snapshot.v20250703142444 --save-exact

@clerk/localizations

npm i @clerk/localizations@3.17.3-snapshot.v20250703142444 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@6.23.3-snapshot.v20250703142444 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@1.7.5-snapshot.v20250703142444 --save-exact

@clerk/clerk-react

npm i @clerk/clerk-react@5.32.4-snapshot.v20250703142444 --save-exact

@clerk/react-router

npm i @clerk/react-router@1.6.4-snapshot.v20250703142444 --save-exact

@clerk/remix

npm i @clerk/remix@4.8.5-snapshot.v20250703142444 --save-exact

@clerk/shared

npm i @clerk/shared@3.10.2-snapshot.v20250703142444 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@0.18.3-snapshot.v20250703142444 --save-exact

@clerk/testing

npm i @clerk/testing@1.9.2-snapshot.v20250703142444 --save-exact

@clerk/themes

npm i @clerk/themes@2.2.54-snapshot.v20250703142444 --save-exact

@clerk/types

npm i @clerk/types@4.63.0-snapshot.v20250703142444 --save-exact

@clerk/vue

npm i @clerk/vue@1.8.12-snapshot.v20250703142444 --save-exact

.changeset/chubby-parts-try.md

alexcarpenter · 2025-07-07T17:57:48Z

!snapshot

clerk-cookie · 2025-07-07T18:00:08Z

Hey @alexcarpenter - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.1.6-snapshot.v20250707175819
@clerk/astro	2.10.3-snapshot.v20250707175819
@clerk/backend	2.4.1-snapshot.v20250707175819
@clerk/chrome-extension	2.5.4-snapshot.v20250707175819
@clerk/clerk-js	5.71.0-snapshot.v20250707175819
@clerk/elements	0.23.38-snapshot.v20250707175819
@clerk/clerk-expo	2.14.3-snapshot.v20250707175819
@clerk/expo-passkeys	0.3.15-snapshot.v20250707175819
@clerk/express	1.7.5-snapshot.v20250707175819
@clerk/fastify	2.4.5-snapshot.v20250707175819
@clerk/localizations	3.17.4-snapshot.v20250707175819
@clerk/nextjs	6.24.0-snapshot.v20250707175819
@clerk/nuxt	1.7.6-snapshot.v20250707175819
@clerk/clerk-react	5.33.0-snapshot.v20250707175819
@clerk/react-router	1.7.0-snapshot.v20250707175819
@clerk/remix	4.9.0-snapshot.v20250707175819
@clerk/shared	3.11.0-snapshot.v20250707175819
@clerk/tanstack-react-start	0.19.0-snapshot.v20250707175819
@clerk/testing	1.9.3-snapshot.v20250707175819
@clerk/themes	2.2.55-snapshot.v20250707175819
@clerk/types	4.64.0-snapshot.v20250707175819
@clerk/vue	1.8.13-snapshot.v20250707175819

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/agent-toolkit@0.1.6-snapshot.v20250707175819 --save-exact

@clerk/astro

npm i @clerk/astro@2.10.3-snapshot.v20250707175819 --save-exact

@clerk/backend

npm i @clerk/backend@2.4.1-snapshot.v20250707175819 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@2.5.4-snapshot.v20250707175819 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@5.71.0-snapshot.v20250707175819 --save-exact

@clerk/elements

npm i @clerk/elements@0.23.38-snapshot.v20250707175819 --save-exact

@clerk/clerk-expo

npm i @clerk/clerk-expo@2.14.3-snapshot.v20250707175819 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@0.3.15-snapshot.v20250707175819 --save-exact

@clerk/express

npm i @clerk/express@1.7.5-snapshot.v20250707175819 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.4.5-snapshot.v20250707175819 --save-exact

@clerk/localizations

npm i @clerk/localizations@3.17.4-snapshot.v20250707175819 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@6.24.0-snapshot.v20250707175819 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@1.7.6-snapshot.v20250707175819 --save-exact

@clerk/clerk-react

npm i @clerk/clerk-react@5.33.0-snapshot.v20250707175819 --save-exact

@clerk/react-router

npm i @clerk/react-router@1.7.0-snapshot.v20250707175819 --save-exact

@clerk/remix

npm i @clerk/remix@4.9.0-snapshot.v20250707175819 --save-exact

@clerk/shared

npm i @clerk/shared@3.11.0-snapshot.v20250707175819 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@0.19.0-snapshot.v20250707175819 --save-exact

@clerk/testing

npm i @clerk/testing@1.9.3-snapshot.v20250707175819 --save-exact

@clerk/themes

npm i @clerk/themes@2.2.55-snapshot.v20250707175819 --save-exact

@clerk/types

npm i @clerk/types@4.64.0-snapshot.v20250707175819 --save-exact

@clerk/vue

npm i @clerk/vue@1.8.13-snapshot.v20250707175819 --save-exact

alexcarpenter added 3 commits June 24, 2025 10:33

refactor(clerk-js): Update color logic utils

652cfe6

checkpoint

8198e12

refactor color utilities

283f322

clerk-cookie added the clerk-js label Jun 24, 2025

remove eslint-disable usage

33a32dd

vercel bot deployed to Preview June 24, 2025 16:35 View deployment

alexcarpenter added 2 commits June 24, 2025 15:44

Enhance sandbox styles and color utilities

7cb8d8a

- Added custom appearance variables in app.ts for improved styling. - Introduced a new CSS variable for brand color in template.html. - Removed unused simpleColorMix function from color utilities in utils.ts.

Update colorOptionToHslaScale.ts

5898f2b

vercel bot deployed to Preview June 24, 2025 20:25 View deployment

creat unified colors interface to manage modern and legacy support

7db3449

vercel bot deployed to Preview June 24, 2025 23:36 View deployment

reorganize colors folder

719ee2a

vercel bot deployed to Preview June 24, 2025 23:59 View deployment

extract constants and cache

c1a3174

vercel bot deployed to Preview June 25, 2025 00:13 View deployment

add tests

df764fc

vercel bot deployed to Preview June 25, 2025 00:45 View deployment

Delete performance.ts

87419bd

vercel bot deployed to Preview June 25, 2025 00:56 View deployment

alexcarpenter added 2 commits June 24, 2025 20:59

Update app.ts

6f1d280

revert sandbox changes

18f15aa

vercel bot deployed to Preview June 25, 2025 01:02 View deployment

alexcarpenter added 2 commits June 25, 2025 12:00

Merge branch 'main' into alexcarpenter/user-2201-add-color-mix-utilities

b7dcccc

add temp changelog

8ea0357

vercel bot deployed to Preview June 25, 2025 16:01 View deployment

vercel bot deployed to Preview June 25, 2025 16:03 View deployment

Merge branch 'main' into alexcarpenter/user-2201-add-color-mix-utilities

120ba37

vercel bot deployed to Preview July 3, 2025 13:43 View deployment

alexcarpenter added 2 commits July 3, 2025 09:48

Update bundlewatch.config.json

b697754

Merge branch 'alexcarpenter/user-2201-add-color-mix-utilities' of git…

0138f04

…hub.com:clerk/javascript into alexcarpenter/user-2201-add-color-mix-utilities

vercel bot deployed to Preview July 3, 2025 13:49 View deployment

alexcarpenter added 2 commits July 7, 2025 09:53

Merge branch 'main' into alexcarpenter/user-2201-add-color-mix-utilities

79c05ca

resolve stripe appearance

82bd682

vercel bot deployed to Preview July 7, 2025 14:25 View deployment

fix stripe appearance

f691fe5

vercel bot deployed to Preview July 7, 2025 14:45 View deployment

alexcarpenter added 2 commits July 7, 2025 10:45

Merge branch 'main' into alexcarpenter/user-2201-add-color-mix-utilities

b5484a5

negative margin

ef6acaf

vercel bot deployed to Preview July 7, 2025 14:47 View deployment

Update bundlewatch.config.json

e15a0ab

vercel bot deployed to Preview July 7, 2025 15:04 View deployment

fix scales test

11e7dff

vercel bot deployed to Preview July 7, 2025 15:08 View deployment

Update bundlewatch.config.json

315070d

vercel bot deployed to Preview July 7, 2025 15:27 View deployment

dstaley approved these changes Jul 7, 2025

View reviewed changes

.changeset/chubby-parts-try.md Outdated Show resolved Hide resolved

tmilewski approved these changes Jul 7, 2025

View reviewed changes

Update chubby-parts-try.md

a84db2d

vercel bot deployed to Preview July 7, 2025 17:35 View deployment

alexcarpenter merged commit 22be9f0 into main Jul 8, 2025
37 checks passed

alexcarpenter deleted the alexcarpenter/user-2201-add-color-mix-utilities branch July 8, 2025 13:14

clerk-cookie mentioned this pull request Jul 8, 2025

ci(repo): Version packages #6256

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(clerk-js): Update color logic utils to support CSS variable usage #6187

feat(clerk-js): Update color logic utils to support CSS variable usage #6187

Uh oh!

alexcarpenter commented Jun 24, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jun 24, 2025 •

edited

Loading

Uh oh!

vercel bot commented Jun 24, 2025 •

edited

Loading

Uh oh!

alexcarpenter commented Jun 25, 2025

Uh oh!

clerk-cookie commented Jun 25, 2025

Uh oh!

alexcarpenter commented Jul 3, 2025

Uh oh!

clerk-cookie commented Jul 3, 2025

Uh oh!

Uh oh!

alexcarpenter commented Jul 7, 2025

Uh oh!

clerk-cookie commented Jul 7, 2025

Uh oh!

Uh oh!

Uh oh!

feat(clerk-js): Update color logic utils to support CSS variable usage #6187

feat(clerk-js): Update color logic utils to support CSS variable usage #6187

Uh oh!

Conversation

alexcarpenter commented Jun 24, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎨 Add Modern CSS Color-Mix Utilities

Overview

What's New

Progressive Enhancement Architecture

Modern CSS Features

CSS Variable Support

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexcarpenter commented Jun 25, 2025

Uh oh!

clerk-cookie commented Jun 25, 2025

Uh oh!

alexcarpenter commented Jul 3, 2025

Uh oh!

clerk-cookie commented Jul 3, 2025

Uh oh!

Uh oh!

alexcarpenter commented Jul 7, 2025

Uh oh!

clerk-cookie commented Jul 7, 2025

Uh oh!

Uh oh!

Uh oh!

alexcarpenter commented Jun 24, 2025 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jun 24, 2025 •

edited

Loading

vercel bot commented Jun 24, 2025 •

edited

Loading