- Notifications
You must be signed in to change notification settings - Fork1.1k
docs: document critical frontend pattern migrations in CLAUDE.md#20949
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.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
base:main
Are you sure you want to change the base?
Conversation
Add comprehensive documentation for active frontend pattern migrationsdiscovered 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 preferencesNew 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 guidedevelopers 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 to1f0280eCompareFix 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 left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 toonly 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 patternThis prevents AI agents from pattern-matching and copying deprecatedcode 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 linesOverall ~30% reduction in text while maintaining clarity. AI agentsscan for patterns and use code examples - keeping prose minimal anddirective 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 allunique information. Each concept is now documented once in its mostappropriate section.
mafredri commentedNov 27, 2025
@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 tomaintain consistency with the original document style which uses noemojis, 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 to453a8acCompare
Uh oh!
There was an error while loading.Please reload this page.
Summary
This PR documents critical frontend pattern migrations based onsystematic 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): swap emotion for tailwind in workspace batch delete dialogue #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 🏂