Skip to content

refactor(clerk-js): Make color ring and modal-backdrop full opacity when modified #7052

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

refactor(clerk-js): Make color ring and modal-backdrop full opacity when modified #7052

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0ba8afb
refactor(clerk-js): Make color ring full opacity when modified
alexcarpenter Oct 22, 2025
a6c8fda
apply same refactor to color-modal-backdrop
alexcarpenter Oct 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions packages/clerk-js/src/ui/customizables/parseVariables.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,11 +74,9 @@ export const createColorScales = (theme: Theme) => {
: colors.toHslaString(variables.colorInputBackground),
colorShimmer: colors.toHslaString(variables.colorShimmer),
colorMuted: variables.colorMuted ? colors.toHslaString(variables.colorMuted) : undefined,
colorRing: variables.colorRing ? colors.makeTransparent(colors.toHslaString(variables.colorRing), 0.85) : undefined,
colorRing: variables.colorRing ? colors.toHslaString(variables.colorRing) : undefined,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

LGTM! Verify the breaking change impact across the codebase.

The removal of the forced 0.85 transparency wrapper correctly implements the PR objective, allowing users to specify exact colors and opacities. The pattern now matches other optional color properties like colorMuted and colorShadow.

However, this is a breaking behavioral change. Existing code or user configurations that rely on the automatic transparency will now see colorRing at full opacity unless they explicitly specify a transparent value.

Run the following script to identify any usages that might be affected by this breaking change:

🏁 Script executed:

#!/bin/bash
# Description: Search for colorRing usage across the codebase to assess breaking change impact

# Search for colorRing property access and usage
rg -nP --type=ts --type=tsx -C3 '\bcolorRing\b'

# Search for --clerk-color-ring CSS variable usage
rg -nP -C3 '--clerk-color-ring'

Length of output: 448

🏁 Script executed:

#!/bin/bash
# Fixed searches for colorRing usage assessment

# Search for colorRing property usage in TypeScript files
echo "=== Searching for colorRing property usage ==="
rg -n -C3 'colorRing' --type=ts

echo ""
echo "=== Searching for CSS variable reference ==="
# Search for --clerk-color-ring CSS variable usage
rg -n -C3 'clerk-color-ring'

echo ""
echo "=== Examining parseVariables.ts context around line 77 ==="
fd -t f parseVariables.ts -x cat {} -n | head -100

Length of output: 13165

🏁 Script executed:

#!/bin/bash
# Understand how parseVariables output is used and merged with foundation defaults

echo "=== Examining parseVariables exports and usage ==="
fd -t f -e ts -e tsx parseVariables -x grep -l 'export\|createColorScales'

echo ""
echo "=== Search for imports of createColorScales ==="
rg -n 'createColorScales' --type=ts

echo ""
echo "=== Check how colors from foundations are used as fallback ==="
rg -n 'colorRing.*clerkCssVar\|clerkCssVar.*colorRing' --type=ts

Length of output: 528

🏁 Script executed:

#!/bin/bash
# Trace how foundation colors merge with parseColorScales output

echo "=== Context around parseAppearance.ts line 162 ==="
fd -t f parseAppearance.ts -x sed -n '150,180p' {}

echo ""
echo "=== Check if foundation colors object is pre-populated ==="
rg -n -B5 -A5 'createColorScales\(theme\)' packages/clerk-js/src/ui/customizables/parseAppearance.ts

echo ""
echo "=== View entire parseAppearance.ts to understand initialization ==="
fd -t f parseAppearance.ts -x wc -l {}

Length of output: 1598

Update JSDoc to reflect breaking change in colorRing opacity behavior.

The removal of makeTransparent(0.85) wrapper is a breaking change for users providing explicit colorRing values. The JSDoc at packages/types/src/appearance.ts:757-759 currently states the color is rendered "at 15% opacity," but this guarantee no longer applies when users provide a custom value—they now get full opacity unless explicitly specified.

Update the documentation to clarify:

  • When colorRing is undefined, the default uses 15% opacity
  • When colorRing is explicitly provided, users control the opacity (no forced transparency)

The implementation itself is correct and matches the pattern of adjacent optional color properties (colorMuted, colorShadow). The consuming code across baseTheme.ts, styledSystem/common.ts, and UI components will work correctly with this change.

🤖 Prompt for AI Agents 
In packages/clerk-js/src/ui/customizables/parseVariables.ts around line 77 and
in the JSDoc at packages/types/src/appearance.ts lines ~757-759, update the
documentation to reflect the breaking change: clarify that when colorRing is
undefined the library uses the default color rendered at 15% opacity, but when
colorRing is explicitly provided the value is used as-is (users control opacity
and no forced transparency is applied). Edit the JSDoc text to state both
behaviors succinctly and ensure examples/param description indicate that opacity
must be included in the custom color if the user wants transparency.

colorShadow: variables.colorShadow ? colors.toHslaString(variables.colorShadow) : undefined,
colorModalBackdrop: variables.colorModalBackdrop
? colors.makeTransparent(colors.toHslaString(variables.colorModalBackdrop), 0.27)
: undefined,
colorModalBackdrop: variables.colorModalBackdrop ? colors.toHslaString(variables.colorModalBackdrop) : undefined,
avatarBackground: neutralAlphaScale?.neutralAlpha400
? colors.toHslaString(neutralAlphaScale.neutralAlpha400)
: undefined,
Expand Down
14 changes: 8 additions & 6 deletions packages/clerk-js/src/ui/foundations/colors.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,17 +88,19 @@ const colorMutedForeground = clerkCssVar(
const colors = Object.freeze({
avatarBorder: neutralAlphaScale.neutralAlpha200,
avatarBackground: neutralAlphaScale.neutralAlpha400,
colorModalBackdrop:
colorUtils.makeTransparent(clerkCssVar('color-modal-backdrop', defaultColorNeutral), 0.27) ||
neutralAlphaScale.neutralAlpha700,
colorModalBackdrop: clerkCssVar(
'color-modal-backdrop',
colorUtils.makeTransparent(defaultColorNeutral, 0.27) || neutralAlphaScale.neutralAlpha700,
),
colorBackground: clerkCssVar('color-background', 'white'),
colorInput: clerkCssVar('color-input', 'white'),
colorForeground,
colorMutedForeground,
colorMuted: undefined,
colorRing:
colorUtils.makeTransparent(clerkCssVar('color-ring', defaultColorNeutral), 0.85) ||
neutralAlphaScale.neutralAlpha200,
colorRing: clerkCssVar(
'color-ring',
colorUtils.makeTransparent(defaultColorNeutral, 0.85) || neutralAlphaScale.neutralAlpha200,
),
colorInputForeground: clerkCssVar('color-input-foreground', '#131316'),
colorPrimaryForeground: clerkCssVar('color-primary-foreground', 'white'),
colorShimmer: clerkCssVar('color-shimmer', 'rgba(255, 255, 255, 0.36)'),
Expand Down
Loading