codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/frontend-dev-guidelines/resources/styling-guide.md

@@ -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