docs: document critical frontend pattern migrations in CLAUDE.md #20949
+124
−22
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add comprehensive documentation for active frontend pattern migrations discovered through analysis of 200+ git commits touching site/ files: Core Migrations: - Emotion → Tailwind CSS (strict 'no new emotion' policy) - MUI Components → Custom/Radix/shadcn (Tooltips, Tables, Buttons) - MUI Icons → lucide-react with specific icon mappings - spyOn → queries parameter for GET endpoint mocks in Storybook - localStorage → user_configs table for user preferences New Documentation: - Icon migration mappings (BusinessIcon→Building2Icon, etc.) - Radix component prop naming conventions (placement→side) - cn() utility usage for conditional className merging - Chromatic testing best practices (prefer snapshots over assertions) Includes concrete before/after examples and migration patterns to guide developers away from deprecated approaches toward current best practices. Analysis based on PRs: #20948, #20946, #20938, #20905, #20900, #20869, #20849, #20808, #20530, #20479, #20261, #20201, #20200, #20193, #20318 --- 🤖 This change was written by Claude Sonnet 4.5 Thinking using mux and reviewed by a human 🏂
2af4fa8 to
1f0280e
Compare
Fix markdown linting errors MD032 and MD031: - Add blank lines around lists (MD032) - Add blank lines around fenced code blocks (MD031) Ensures site/CLAUDE.md passes markdownlint-cli2 checks.
aslilac
reviewed
Nov 26, 2025
Member
aslilac
left a comment
There was a problem hiding this comment.
seems to mostly make sense
one small worry: having the "don't"s in here puts them in the context window, and I worry that might some models might pick up on that and just ignore the "don't". I wonder if it might be better to only put the new equivalent? totally guessing tho
@jaaydenh has more experience with this kind of tuning so I'd love to here from him
Remove code examples showing deprecated patterns (OLD/DO NOT USE blocks) that could mislead AI agents into copying the wrong patterns. Changes: - Icon section: Only show lucide-react imports, not MUI icons - Radix section: Only show correct Radix pattern, not MUI pattern - Emotion section: Only show Tailwind classes, not emotion imports - Testing section: Only show queries parameter, not spyOn pattern This prevents AI agents from pattern-matching and copying deprecated code while maintaining clear guidance on what to replace and how.
Condense verbose sections to be more scannable and direct: - Icon section: Single-line import, inline replacement mappings - Radix section: Consolidated prop changes into one sentence - Emotion section: Reduced from 5 to 4 bullets, combined redundant points - Chromatic section: Reduced from 5 to 3 bullets - localStorage section: Reduced from 8 to 4 lines Overall ~30% reduction in text while maintaining clarity. AI agents scan for patterns and use code examples - keeping prose minimal and directive improves efficiency.
Remove redundant sections and repeated information: - Remove entire "Migration" section (lines 192-207) that duplicated Components, Styling, and Tailwind sections - Remove duplicate "leave campsite better" mention (already in line 13) - Remove duplicate "Never import from @emotion/react" (already stated) Reduces documentation from 250 to 232 lines while maintaining all unique information. Each concept is now documented once in its most appropriate section.
Member
Author
|
@aslilac personally I don't think the don't examples would be mistaken, but at the same time, they add length, wordiness and context size. So I opted to have the doc simplified, both in their removal and reduced wording. There I guess the only tradeoff is how easily the old patterns are detected, but that's also not "free". |
Remove 🚨 emoji from "Critical Pattern Migrations" section header to maintain consistency with the original document style which uses no emojis, only text emphasis and formatting. All other style elements match the original: - Section headers with ## and ### - Bold emphasis for important terms - Simple bullet lists with - - Direct, imperative tone - "(MUST FOLLOW)" matches original "(USE FIRST)" pattern
21f5f0e to
453a8ac
Compare
jaaydenh
reviewed
Dec 1, 2025
|
|
||
| ### Icon Migration: MUI Icons → lucide-react | ||
|
|
||
| Never import from `@mui/icons-material`. Use `lucide-react` instead. |
Contributor
There was a problem hiding this comment.
@mui/icons-material is no longer used in the codebase, I think its highly unlikely the AI will suggest using a MUI icon anymore without any usages in the codebase.
jaaydenh
reviewed
Dec 1, 2025
| When migrating from MUI to Radix components, use Radix naming conventions: | ||
|
|
||
| ```tsx | ||
| <Tooltip side="top"> |
Contributor
There was a problem hiding this comment.
Tooltip migration will be completed soon, so this may not be the best example long-term, but could be fine for now.
jaaydenh
approved these changes
Dec 1, 2025
Contributor
jaaydenh
left a comment
There was a problem hiding this comment.
I think the only change needed is removing the section about MUI Icons
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR documents critical frontend pattern migrations based on systematic analysis of 200+ git commits that modified
site/files. These patterns have been causing repeated feedback in PR reviews and need to be clearly documented for AI and human developers.Analysis Method
Used
git logto identify actual pattern migrations:site/directoryPatterns Documented
1. Emotion → Tailwind CSS
@emotion/reactto Tailwind CSS@emotion/reactfrom<404Page />#20530, refactor: migrate deployment banner to Tailwind and radix #20479, chore: migrate appearanceform to Tailwind and shadcn #20204, refactor(site): convert workspace batch delete dialog to Tailwind CSS #209462. MUI Components → Custom/Radix/shadcn
3. MUI Icons → lucide-react (NEW)
BusinessIcon→Building2IconGroupOutlinedIcon→UsersIconPublicOutlinedIcon→GlobeIconPersonIcon→UserIcon4. Radix Component Prop Naming (NEW)
placement→sidePopperPropsremoved (internal implementation detail)5. Testing: spyOn → queries parameter
6. State Storage: localStorage → user_configs
theme_preferenceas reference implementation7. Chromatic Testing Best Practices
8. cn() Utility for Conditional Classes (NEW)
clsxandtailwind-mergeChanges Made
site/CLAUDE.mdwith comprehensive pattern documentationGit Statistics
site/directoryKey PRs Referenced
#20948, #20946, #20938, #20933, #20905, #20900, #20869, #20849, #20808, #20530, #20479, #20318, #20261, #20204, #20201, #20200, #20193
🤖 This change was written by Claude Sonnet 4.5 Thinking using mux and reviewed by a human 🏂