init
This commit is contained in:
428
.opencode/skills/frontend-development/resources/styling-guide.md
Normal file
428
.opencode/skills/frontend-development/resources/styling-guide.md
Normal file
@@ -0,0 +1,428 @@
|
||||
# Styling Guide
|
||||
|
||||
Modern styling patterns for using MUI v7 sx prop, inline styles, and theme integration.
|
||||
|
||||
---
|
||||
|
||||
## Inline vs Separate Styles
|
||||
|
||||
### Decision Threshold
|
||||
|
||||
**<100 lines: Inline styles at top of component**
|
||||
|
||||
```typescript
|
||||
import type { SxProps, Theme } from '@mui/material';
|
||||
|
||||
const componentStyles: Record<string, SxProps<Theme>> = {
|
||||
container: {
|
||||
p: 2,
|
||||
display: 'flex',
|
||||
flexDirection: 'column',
|
||||
},
|
||||
header: {
|
||||
mb: 2,
|
||||
borderBottom: '1px solid',
|
||||
borderColor: 'divider',
|
||||
},
|
||||
// ... more styles
|
||||
};
|
||||
|
||||
export const MyComponent: React.FC = () => {
|
||||
return (
|
||||
<Box sx={componentStyles.container}>
|
||||
<Box sx={componentStyles.header}>
|
||||
<h2>Title</h2>
|
||||
</Box>
|
||||
</Box>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
**>100 lines: Separate `.styles.ts` file**
|
||||
|
||||
```typescript
|
||||
// MyComponent.styles.ts
|
||||
import type { SxProps, Theme } from '@mui/material';
|
||||
|
||||
export const componentStyles: Record<string, SxProps<Theme>> = {
|
||||
container: { ... },
|
||||
header: { ... },
|
||||
// ... 100+ lines of styles
|
||||
};
|
||||
|
||||
// MyComponent.tsx
|
||||
import { componentStyles } from './MyComponent.styles';
|
||||
|
||||
export const MyComponent: React.FC = () => {
|
||||
return <Box sx={componentStyles.container}>...</Box>;
|
||||
};
|
||||
```
|
||||
|
||||
### Real Example: UnifiedForm.tsx
|
||||
|
||||
**Lines 48-126**: 78 lines of inline styles (acceptable)
|
||||
|
||||
```typescript
|
||||
const formStyles: Record<string, SxProps<Theme>> = {
|
||||
gridContainer: {
|
||||
height: '100%',
|
||||
maxHeight: 'calc(100vh - 220px)',
|
||||
},
|
||||
section: {
|
||||
height: '100%',
|
||||
maxHeight: 'calc(100vh - 220px)',
|
||||
overflow: 'auto',
|
||||
p: 4,
|
||||
},
|
||||
// ... 15 more style objects
|
||||
};
|
||||
```
|
||||
|
||||
**Guideline**: User is comfortable with ~80 lines inline. Use your judgment around 100 lines.
|
||||
|
||||
---
|
||||
|
||||
## sx Prop Patterns
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```typescript
|
||||
<Box sx={{ p: 2, mb: 3, display: 'flex' }}>
|
||||
Content
|
||||
</Box>
|
||||
```
|
||||
|
||||
### With Theme Access
|
||||
|
||||
```typescript
|
||||
<Box
|
||||
sx={{
|
||||
p: 2,
|
||||
backgroundColor: (theme) => theme.palette.primary.main,
|
||||
color: (theme) => theme.palette.primary.contrastText,
|
||||
borderRadius: (theme) => theme.shape.borderRadius,
|
||||
}}
|
||||
>
|
||||
Themed Box
|
||||
</Box>
|
||||
```
|
||||
|
||||
### Responsive Styles
|
||||
|
||||
```typescript
|
||||
<Box
|
||||
sx={{
|
||||
p: { xs: 1, sm: 2, md: 3 },
|
||||
width: { xs: '100%', md: '50%' },
|
||||
flexDirection: { xs: 'column', md: 'row' },
|
||||
}}
|
||||
>
|
||||
Responsive Layout
|
||||
</Box>
|
||||
```
|
||||
|
||||
### Pseudo-Selectors
|
||||
|
||||
```typescript
|
||||
<Box
|
||||
sx={{
|
||||
p: 2,
|
||||
'&:hover': {
|
||||
backgroundColor: 'rgba(0,0,0,0.05)',
|
||||
},
|
||||
'&:active': {
|
||||
backgroundColor: 'rgba(0,0,0,0.1)',
|
||||
},
|
||||
'& .child-class': {
|
||||
color: 'primary.main',
|
||||
},
|
||||
}}
|
||||
>
|
||||
Interactive Box
|
||||
</Box>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MUI v7 Patterns
|
||||
|
||||
### Grid Component (v7 Syntax)
|
||||
|
||||
```typescript
|
||||
import { Grid } from '@mui/material';
|
||||
|
||||
// ✅ CORRECT - v7 syntax with size prop
|
||||
<Grid container spacing={2}>
|
||||
<Grid size={{ xs: 12, md: 6 }}>
|
||||
Left Column
|
||||
</Grid>
|
||||
<Grid size={{ xs: 12, md: 6 }}>
|
||||
Right Column
|
||||
</Grid>
|
||||
</Grid>
|
||||
|
||||
// ❌ WRONG - Old v6 syntax
|
||||
<Grid container spacing={2}>
|
||||
<Grid xs={12} md={6}> {/* OLD - Don't use */}
|
||||
Content
|
||||
</Grid>
|
||||
</Grid>
|
||||
```
|
||||
|
||||
**Key Change**: `size={{ xs: 12, md: 6 }}` instead of `xs={12} md={6}`
|
||||
|
||||
### Responsive Grid
|
||||
|
||||
```typescript
|
||||
<Grid container spacing={3}>
|
||||
<Grid size={{ xs: 12, sm: 6, md: 4, lg: 3 }}>
|
||||
Responsive Column
|
||||
</Grid>
|
||||
</Grid>
|
||||
```
|
||||
|
||||
### Nested Grids
|
||||
|
||||
```typescript
|
||||
<Grid container spacing={2}>
|
||||
<Grid size={{ xs: 12, md: 8 }}>
|
||||
<Grid container spacing={1}>
|
||||
<Grid size={{ xs: 12, sm: 6 }}>
|
||||
Nested 1
|
||||
</Grid>
|
||||
<Grid size={{ xs: 12, sm: 6 }}>
|
||||
Nested 2
|
||||
</Grid>
|
||||
</Grid>
|
||||
</Grid>
|
||||
|
||||
<Grid size={{ xs: 12, md: 4 }}>
|
||||
Sidebar
|
||||
</Grid>
|
||||
</Grid>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type-Safe Styles
|
||||
|
||||
### Style Object Type
|
||||
|
||||
```typescript
|
||||
import type { SxProps, Theme } from '@mui/material';
|
||||
|
||||
// Type-safe styles
|
||||
const styles: Record<string, SxProps<Theme>> = {
|
||||
container: {
|
||||
p: 2,
|
||||
// Autocomplete and type checking work here
|
||||
},
|
||||
};
|
||||
|
||||
// Or individual style
|
||||
const containerStyle: SxProps<Theme> = {
|
||||
p: 2,
|
||||
display: 'flex',
|
||||
};
|
||||
```
|
||||
|
||||
### Theme-Aware Styles
|
||||
|
||||
```typescript
|
||||
const styles: Record<string, SxProps<Theme>> = {
|
||||
primary: {
|
||||
color: (theme) => theme.palette.primary.main,
|
||||
backgroundColor: (theme) => theme.palette.primary.light,
|
||||
'&:hover': {
|
||||
backgroundColor: (theme) => theme.palette.primary.dark,
|
||||
},
|
||||
},
|
||||
customSpacing: {
|
||||
padding: (theme) => theme.spacing(2),
|
||||
margin: (theme) => theme.spacing(1, 2), // top/bottom: 1, left/right: 2
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What NOT to Use
|
||||
|
||||
### ❌ makeStyles (MUI v4 pattern)
|
||||
|
||||
```typescript
|
||||
// ❌ AVOID - Old Material-UI v4 pattern
|
||||
import { makeStyles } from '@mui/styles';
|
||||
|
||||
const useStyles = makeStyles((theme) => ({
|
||||
root: {
|
||||
padding: theme.spacing(2),
|
||||
},
|
||||
}));
|
||||
```
|
||||
|
||||
**Why avoid**: Deprecated, v7 doesn't support it well
|
||||
|
||||
### ❌ styled() Components
|
||||
|
||||
```typescript
|
||||
// ❌ AVOID - styled-components pattern
|
||||
import { styled } from '@mui/material/styles';
|
||||
|
||||
const StyledBox = styled(Box)(({ theme }) => ({
|
||||
padding: theme.spacing(2),
|
||||
}));
|
||||
```
|
||||
|
||||
**Why avoid**: sx prop is more flexible and doesn't create new components
|
||||
|
||||
### ✅ Use sx Prop Instead
|
||||
|
||||
```typescript
|
||||
// ✅ PREFERRED
|
||||
<Box
|
||||
sx={{
|
||||
p: 2,
|
||||
backgroundColor: 'primary.main',
|
||||
}}
|
||||
>
|
||||
Content
|
||||
</Box>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Style Standards
|
||||
|
||||
### Indentation
|
||||
|
||||
**4 spaces** (not 2, not tabs)
|
||||
|
||||
```typescript
|
||||
const styles: Record<string, SxProps<Theme>> = {
|
||||
container: {
|
||||
p: 2,
|
||||
display: 'flex',
|
||||
flexDirection: 'column',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Quotes
|
||||
|
||||
**Single quotes** for strings (project standard)
|
||||
|
||||
```typescript
|
||||
// ✅ CORRECT
|
||||
const color = 'primary.main';
|
||||
import { Box } from '@mui/material';
|
||||
|
||||
// ❌ WRONG
|
||||
const color = "primary.main";
|
||||
import { Box } from "@mui/material";
|
||||
```
|
||||
|
||||
### Trailing Commas
|
||||
|
||||
**Always use trailing commas** in objects and arrays
|
||||
|
||||
```typescript
|
||||
// ✅ CORRECT
|
||||
const styles = {
|
||||
container: { p: 2 },
|
||||
header: { mb: 1 }, // Trailing comma
|
||||
};
|
||||
|
||||
const items = [
|
||||
'item1',
|
||||
'item2', // Trailing comma
|
||||
];
|
||||
|
||||
// ❌ WRONG - No trailing comma
|
||||
const styles = {
|
||||
container: { p: 2 },
|
||||
header: { mb: 1 } // Missing comma
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Style Patterns
|
||||
|
||||
### Flexbox Layout
|
||||
|
||||
```typescript
|
||||
const styles = {
|
||||
flexRow: {
|
||||
display: 'flex',
|
||||
flexDirection: 'row',
|
||||
alignItems: 'center',
|
||||
gap: 2,
|
||||
},
|
||||
flexColumn: {
|
||||
display: 'flex',
|
||||
flexDirection: 'column',
|
||||
gap: 1,
|
||||
},
|
||||
spaceBetween: {
|
||||
display: 'flex',
|
||||
justifyContent: 'space-between',
|
||||
alignItems: 'center',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Spacing
|
||||
|
||||
```typescript
|
||||
// Padding
|
||||
p: 2 // All sides
|
||||
px: 2 // Horizontal (left + right)
|
||||
py: 2 // Vertical (top + bottom)
|
||||
pt: 2, pr: 1 // Specific sides
|
||||
|
||||
// Margin
|
||||
m: 2, mx: 2, my: 2, mt: 2, mr: 1
|
||||
|
||||
// Units: 1 = 8px (theme.spacing(1))
|
||||
p: 2 // = 16px
|
||||
p: 0.5 // = 4px
|
||||
```
|
||||
|
||||
### Positioning
|
||||
|
||||
```typescript
|
||||
const styles = {
|
||||
relative: {
|
||||
position: 'relative',
|
||||
},
|
||||
absolute: {
|
||||
position: 'absolute',
|
||||
top: 0,
|
||||
right: 0,
|
||||
},
|
||||
sticky: {
|
||||
position: 'sticky',
|
||||
top: 0,
|
||||
zIndex: 1000,
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Styling Checklist:**
|
||||
- ✅ Use `sx` prop for MUI styling
|
||||
- ✅ Type-safe with `SxProps<Theme>`
|
||||
- ✅ <100 lines: inline; >100 lines: separate file
|
||||
- ✅ MUI v7 Grid: `size={{ xs: 12 }}`
|
||||
- ✅ 4 space indentation
|
||||
- ✅ Single quotes
|
||||
- ✅ Trailing commas
|
||||
- ❌ No makeStyles or styled()
|
||||
|
||||
**See Also:**
|
||||
- [component-patterns.md](component-patterns.md) - Component structure
|
||||
- [complete-examples.md](complete-examples.md) - Full styling examples
|
||||
Reference in New Issue
Block a user