Skip to content

Commit f72c0cb

Browse files
Copilotrenemadsen
Copilot
and
renemadsen
committed
Add comprehensive SCSS structure and M3 migration guide
Co-authored-by: renemadsen <[email protected]>
1 parent 4f6e27a commit f72c0cb

File tree

1 file changed

+353
-0
lines changed

1 file changed

+353
-0
lines changed

‎eform-client/SCSS_MIGRATION_GUIDE.md‎

Lines changed: 353 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,353 @@
1+
# SCSS Structure and Material 3 Migration Guide
2+
3+
## Overview
4+
5+
This document provides an overview of the SCSS structure in the eForm Angular frontend and guidance for future migration to Angular Material 3 (M3).
6+
7+
## Current State
8+
9+
The application currently uses **Angular Material 20.x** with **Material 2 (M2) theme APIs**. The SCSS files have been refactored to follow best practices and are well-organized for future M3 migration.
10+
11+
### SCSS File Structure
12+
13+
```
14+
src/scss/
15+
├── components/ # Component-specific styles
16+
│ ├── _index.scss # Component imports (organized by type)
17+
│ ├── _button.scss # Button styles
18+
│ ├── _card.scss # Card utilities
19+
│ ├── _chart.scss # Chart theming (ngx-charts)
20+
│ ├── _form.scss # Form field utilities
21+
│ ├── _modal.scss # Modal customization
22+
│ ├── _table.scss # Table theming (mtx-grid)
23+
│ ├── _text.scss # Text utilities and colors
24+
│ └── ... # Other component files
25+
├── libs/ # Third-party library styles
26+
│ ├── _index.scss # Library imports
27+
│ ├── theme.scss # Main theme configuration
28+
│ └── ... # Library-specific styles
29+
├── utilities/ # Utility classes and variables
30+
│ ├── _index.scss # Utilities index
31+
│ ├── _colors.scss # Color variables
32+
│ ├── _variables.scss # Global variables
33+
│ ├── _flex.scss # Flexbox utilities
34+
│ ├── _grid.scss # Grid utilities
35+
│ ├── _spacing.scss # Spacing utilities
36+
│ └── ... # Other utilities
37+
└── styles.scss # Global styles and entry point
38+
```
39+
40+
## Theme Configuration
41+
42+
### Current Implementation (M2)
43+
44+
The theme is configured in `src/scss/libs/theme.scss`:
45+
46+
```scss
47+
// Typography
48+
$eform-typography: mat.m2-define-typography-config(...);
49+
50+
// Color Palettes
51+
$eform-light-primary: mat.m2-define-palette(mat.$m2-indigo-palette);
52+
$eform-light-accent: mat.m2-define-palette(mat.$m2-pink-palette);
53+
54+
// Theme Definitions
55+
$eform-light-theme: mat.m2-define-light-theme((
56+
color: (
57+
primary: $eform-light-primary,
58+
accent: $eform-light-accent,
59+
),
60+
typography: $eform-typography,
61+
));
62+
```
63+
64+
### Theme Application
65+
66+
Themes are applied to both light and dark modes:
67+
68+
```scss
69+
body {
70+
@each $key, $val in (('light', $eform-light-theme), ('dark', $eform-dark-theme)) {
71+
&.theme-#{$key} {
72+
@include mat.all-component-themes($val);
73+
@include mtx.all-component-themes($val);
74+
// ... other component themes
75+
}
76+
}
77+
}
78+
```
79+
80+
## Component Theming
81+
82+
### Current Pattern
83+
84+
Component SCSS files use mixins to apply theme-aware styles:
85+
86+
```scss
87+
@mixin color($theme) {
88+
$color-config: mat.m2-get-color-config($theme);
89+
// Apply theme colors
90+
}
91+
92+
@mixin typography($theme) {
93+
$typography-config: mat.m2-get-typography-config($theme);
94+
// Apply typography
95+
}
96+
97+
@mixin theme($theme) {
98+
$color-config: mat.m2-get-color-config($theme);
99+
@if $color-config != null {
100+
@include color($theme);
101+
@include typography($theme);
102+
}
103+
}
104+
```
105+
106+
## Material 3 Migration Plan
107+
108+
### When to Migrate
109+
110+
Consider migrating to M3 when:
111+
- Angular Material officially deprecates M2 APIs
112+
- New features are only available in M3
113+
- The team is ready for a comprehensive update
114+
115+
### Migration Steps
116+
117+
#### 1. Update Theme Configuration
118+
119+
Replace M2 theme functions with M3 equivalents in `libs/theme.scss`:
120+
121+
**Before (M2):**
122+
```scss
123+
$eform-typography: mat.m2-define-typography-config(...);
124+
$eform-light-theme: mat.m2-define-light-theme(...);
125+
```
126+
127+
**After (M3):**
128+
```scss
129+
$eform-typography: mat.define-typography-config(...);
130+
$eform-light-theme: mat.define-theme((
131+
color: (
132+
theme-type: light,
133+
primary: mat.$azure-palette,
134+
),
135+
));
136+
```
137+
138+
#### 2. Update Color API Calls
139+
140+
Replace M2 color functions in component files:
141+
142+
**Before (M2):**
143+
```scss
144+
@mixin color($theme) {
145+
$color-config: mat.m2-get-color-config($theme);
146+
$primary: map.get($color-config, 'primary');
147+
color: mat.m2-get-color-from-palette($primary, 500);
148+
}
149+
```
150+
151+
**After (M3):**
152+
```scss
153+
@mixin color($theme) {
154+
color: mat.get-theme-color($theme, primary);
155+
}
156+
```
157+
158+
#### 3. Update Typography API Calls
159+
160+
Replace M2 typography functions:
161+
162+
**Before (M2):**
163+
```scss
164+
@mixin typography($theme) {
165+
$typography-config: mat.m2-get-typography-config($theme);
166+
$body-text: map.get($typography-config, 'body-1');
167+
}
168+
```
169+
170+
**After (M3):**
171+
```scss
172+
@mixin typography($theme) {
173+
$typography-config: mat.get-theme-typography($theme);
174+
font: mat.get-theme-typography($theme, body-large);
175+
}
176+
```
177+
178+
#### 4. Update Component Mixins
179+
180+
Update all component theme mixins in the `components/` directory to use M3 APIs.
181+
182+
#### 5. Test Thoroughly
183+
184+
- Test both light and dark themes
185+
- Verify all component styles render correctly
186+
- Check responsive behavior
187+
- Test across different browsers
188+
189+
### Files to Update
190+
191+
When migrating to M3, update these files:
192+
193+
1. **libs/theme.scss** - Main theme configuration
194+
2. **components/_text.scss** - Color utilities
195+
3. **components/_table.scss** - Table theming
196+
4. **components/_chart.scss** - Chart theming
197+
5. Any other files using `m2-` prefixed functions
198+
199+
### Search for M2 API Usage
200+
201+
To find all M2 API usages, run:
202+
203+
```bash
204+
grep -r "m2-" src/scss/
205+
```
206+
207+
Current M2 API usages (as of last refactoring):
208+
- `mat.m2-define-typography-config`
209+
- `mat.m2-define-typography-level`
210+
- `mat.m2-define-palette`
211+
- `mat.m2-define-light-theme`
212+
- `mat.m2-define-dark-theme`
213+
- `mat.m2-get-color-config`
214+
- `mat.m2-get-typography-config`
215+
- `mat.m2-get-color-from-palette`
216+
217+
## Best Practices
218+
219+
### 1. Use @use and @forward
220+
221+
✅ **Do:**
222+
```scss
223+
@use '@angular/material' as mat;
224+
@use '../utilities/colors' as *;
225+
```
226+
227+
❌ **Don't:**
228+
```scss
229+
@import '@angular/material';
230+
@import '../utilities/colors';
231+
```
232+
233+
### 2. Organize Styles Logically
234+
235+
Group related styles together and use clear section headers:
236+
237+
```scss
238+
/**
239+
* Section Name
240+
*
241+
* Description of what this section contains.
242+
*/
243+
.class-name {
244+
// styles
245+
}
246+
```
247+
248+
### 3. Document Complex Patterns
249+
250+
Add comments explaining non-obvious behavior:
251+
252+
```scss
253+
/**
254+
* Progress Circle Component
255+
*
256+
* Uses CSS conic-gradient for the progress arc.
257+
* The --percentage custom property controls the fill.
258+
*/
259+
.progress-circle {
260+
background: conic-gradient(
261+
#319c4c 0%,
262+
#319c4c calc(var(--percentage) * 1%),
263+
lightgrey calc(var(--percentage) * 1%)
264+
);
265+
}
266+
```
267+
268+
### 4. Use CSS Custom Properties for Theming
269+
270+
Leverage CSS variables for dynamic theming:
271+
272+
```scss
273+
body, .theme-light {
274+
--theme-body-font-color: #242729;
275+
--tp-td-bg: #ffffff;
276+
}
277+
278+
body, .theme-dark {
279+
--theme-body-font-color: #e6e6e6;
280+
--tp-td-bg: #424242;
281+
}
282+
```
283+
284+
### 5. Keep Specificity Low
285+
286+
Avoid overly specific selectors when possible:
287+
288+
✅ **Do:**
289+
```scss
290+
.status-active {
291+
color: #fff;
292+
293+
span {
294+
color: #fff;
295+
}
296+
}
297+
```
298+
299+
❌ **Don't:**
300+
```scss
301+
body .container .status-active span {
302+
color: #fff;
303+
}
304+
```
305+
306+
## Troubleshooting
307+
308+
### Build Errors After Changes
309+
310+
If you encounter build errors:
311+
312+
1. Clear the build cache: `rm -rf dist/`
313+
2. Reinstall dependencies: `yarn install`
314+
3. Rebuild: `yarn build`
315+
316+
### Style Not Applying
317+
318+
If styles aren't applying:
319+
320+
1. Check import order in `_index.scss` files
321+
2. Verify CSS specificity isn't being overridden
322+
3. Use browser DevTools to inspect computed styles
323+
4. Check that theme mixins are included correctly
324+
325+
### Dark Theme Issues
326+
327+
If dark theme styles are incorrect:
328+
329+
1. Verify theme class is applied to `body` element
330+
2. Check CSS custom properties are defined for both themes
331+
3. Ensure component theme mixins check for `is-dark-theme`
332+
333+
## Resources
334+
335+
- [Angular Material Theming Guide](https://material.angular.io/guide/theming)
336+
- [Material Design 3](https://m3.material.io/)
337+
- [Sass Documentation](https://sass-lang.com/documentation)
338+
- [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)
339+
340+
## Questions?
341+
342+
If you have questions about the SCSS structure or M3 migration:
343+
344+
1. Review this guide thoroughly
345+
2. Check the inline comments in SCSS files
346+
3. Consult the Angular Material documentation
347+
4. Reach out to the development team
348+
349+
---
350+
351+
**Last Updated:** 2025-11-16
352+
**Angular Material Version:** 20.1.2
353+
**Theme API:** Material 2 (M2) - Compatible with M3

0 commit comments

Comments
 (0)