chore(repo): Create styling and theming architecture doc #7573
Conversation
🦋 Changeset detectedLatest commit: 6c8da45 The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types 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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis pull request introduces two new files: a changeset entry file and a comprehensive documentation file. The changeset file serves as a placeholder entry at 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
@clerk/agent-toolkit
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.cursor/rules/clerk-ui-theming.mdc:
- Around line 451-467: The Prebuilt Themes reference includes a non-existent
entry for the "lightDark.ts" theme in the Prebuilt Themes section; open the
Prebuilt Themes table in the document and either remove the "lightDark.ts" entry
or replace it with the correct existing theme file name from the themes folder
(verify the actual file in packages/ui/src/themes and update the table entry
accordingly) so the Key Files Reference only lists real paths.
📜 Review details
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
.changeset/upset-loops-enjoy.md.cursor/rules/clerk-ui-theming.mdc
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (18)
- GitHub Check: Static analysis
- GitHub Check: Unit Tests (**)
- GitHub Check: Integration Tests (localhost, chrome)
- GitHub Check: Integration Tests (astro, chrome)
- GitHub Check: Integration Tests (nextjs, chrome, 15)
- GitHub Check: Integration Tests (quickstart, chrome, 15)
- GitHub Check: Integration Tests (billing, chrome, RQ)
- GitHub Check: Integration Tests (custom, chrome)
- GitHub Check: Integration Tests (quickstart, chrome, 16)
- GitHub Check: Integration Tests (billing, chrome)
- GitHub Check: Integration Tests (nextjs, chrome, 16, RQ)
- GitHub Check: Integration Tests (generic, chrome)
- GitHub Check: Integration Tests (nextjs, chrome, 16)
- GitHub Check: Integration Tests (machine, chrome)
- GitHub Check: Integration Tests (ap-flows, chrome)
- GitHub Check: Integration Tests (sessions:staging, chrome)
- GitHub Check: Integration Tests (machine, chrome, RQ)
- GitHub Check: Integration Tests (sessions, chrome)
🔇 Additional comments (8)
.cursor/rules/clerk-ui-theming.mdc (8)
1-5: YAML metadata is correctly configured for Cursor rules.The front matter structure follows the Cursor .mdc format with appropriate globs pattern for TypeScript files in the UI package.
6-36: Architecture overview is clear and well-illustrated.The Mermaid diagram effectively shows the component relationships and data flow through the theming system.
38-75: Design token documentation is comprehensive.Clearly explains the internal theme structure and token access patterns. File path references should be verified to ensure they match the actual codebase structure.
77-157: Appearance API and Element Descriptors sections are well-documented.Shows clear examples of customization layers and descriptor-based styling. The code examples effectively demonstrate how these systems work.
159-332: Styled system, theme creation, and CSS variables sections are thorough.Detailed examples of the variant system, theme cascade, and color scale generation. Color scale documentation explains both modern and legacy browser fallbacks well.
377-400: Verify the emoji separator in generated class names.Line 385 mentions an emoji separator
🔒️appended to generated classnames for "visual identification," which seems unusual. Please verify that this is actually implemented in the class generation code—it's unclear if this is literal output in generated styles or just documentation shorthand.
494-541: Emotion integration and best practices sections are well-structured.Clear explanation of how Emotion is integrated, responsive utilities available, and actionable best practices. The best practices section (#1-7) provides good guidance for maintaining consistency.
543-598: Common patterns section provides helpful real-world examples.Practical examples show customizing single elements, theme-aware styling, component-specific theming, and using prebuilt themes. These examples make the documentation more applicable.
| ## Key Files Reference | ||
|
|
||
| | Purpose | Path | | ||
| |---------|------| | ||
| | Appearance Types | `packages/ui/src/internal/appearance.ts` | | ||
| | Base Theme | `packages/ui/src/baseTheme.ts` | | ||
| | Theme Creator | `packages/ui/src/themes/createTheme.ts` | | ||
| | Element Descriptors | `packages/ui/src/customizables/elementDescriptors.ts` | | ||
| | Appearance Parsing | `packages/ui/src/customizables/parseAppearance.ts` | | ||
| | Variables Parsing | `packages/ui/src/customizables/parseVariables.ts` | | ||
| | Class Generation | `packages/ui/src/customizables/classGeneration.ts` | | ||
| | Design Foundations | `packages/ui/src/foundations/` | | ||
| | Variant System | `packages/ui/src/styledSystem/createVariants.ts` | | ||
| | Prebuilt Themes | `packages/ui/src/themes/` | | ||
| | Color Utilities | `packages/ui/src/utils/colors/` | | ||
| | CSS Variables | `packages/ui/src/utils/cssVariables.ts` | | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify that all referenced file paths in the documentation exist
# Expected files from the Key Files Reference table (lines 451-467)
files_to_check=(
"packages/ui/src/internal/appearance.ts"
"packages/ui/src/baseTheme.ts"
"packages/ui/src/themes/createTheme.ts"
"packages/ui/src/customizables/elementDescriptors.ts"
"packages/ui/src/customizables/parseAppearance.ts"
"packages/ui/src/customizables/parseVariables.ts"
"packages/ui/src/customizables/classGeneration.ts"
"packages/ui/src/styledSystem/createVariants.ts"
"packages/ui/src/utils/cssVariables.ts"
)
# Foundation files referenced in lines 42-49
foundation_files=(
"packages/ui/src/foundations/defaultFoundations.ts"
"packages/ui/src/foundations/colors.ts"
"packages/ui/src/foundations/sizes.ts"
"packages/ui/src/foundations/shadows.ts"
"packages/ui/src/foundations/typography.ts"
)
# Prebuilt themes referenced in lines 434-439
theme_files=(
"packages/ui/src/themes/dark.ts"
"packages/ui/src/themes/shadcn.ts"
"packages/ui/src/themes/neobrutalism.ts"
"packages/ui/src/themes/lightDark.ts"
"packages/ui/src/themes/shadesOfPurple.ts"
)
all_files=("${files_to_check[@]}" "${foundation_files[@]}" "${theme_files[@]}")
echo "Checking existence of documented file paths..."
missing_files=()
for file in "${all_files[@]}"; do
if [ ! -f "$file" ]; then
missing_files+=("$file")
echo "❌ NOT FOUND: $file"
else
echo "✓ FOUND: $file"
fi
done
if [ ${#missing_files[@]} -gt 0 ]; then
echo ""
echo "Summary: ${#missing_files[@]} file(s) referenced in documentation were not found:"
printf '%s\n' "${missing_files[@]}"
exit 1
else
echo ""
echo "✓ All documented file paths exist!"
exit 0
fiRepository: clerk/javascript
Length of output: 1156
Correct packages/ui/src/themes/lightDark.ts path in prebuilt themes section.
The Key Files Reference table is accurate—all paths exist. However, packages/ui/src/themes/lightDark.ts referenced in the prebuilt themes section does not exist and should be removed or corrected to the actual theme file path.
🤖 Prompt for AI Agents
In @.cursor/rules/clerk-ui-theming.mdc around lines 451 - 467, The Prebuilt
Themes reference includes a non-existent entry for the "lightDark.ts" theme in
the Prebuilt Themes section; open the Prebuilt Themes table in the document and
either remove the "lightDark.ts" entry or replace it with the correct existing
theme file name from the themes folder (verify the actual file in
packages/ui/src/themes and update the table entry accordingly) so the Key Files
Reference only lists real paths.
There was a problem hiding this comment.
@alexcarpenter, thank you for clarifying! That makes perfect sense—documenting ahead of the incoming PR #7560. Once that PR lands, the path reference will be valid. No changes needed here.
✏️ Learnings added
Learnt from: alexcarpenter
Repo: clerk/javascript PR: 7573
File: .cursor/rules/clerk-ui-theming.mdc:451-467
Timestamp: 2026-01-09T15:41:19.758Z
Learning: In the clerk/javascript repository, documentation in `.cursor/rules/` may reference files from incoming PRs that haven't merged yet, which is acceptable when the user confirms the file is coming from a specific pending PR.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
Description
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit
Documentation
Chores
✏️ Tip: You can customize this high-level summary in your review settings.