@turk.net/mui 3.0.6

package/.opencode/skills/turknet-onehub-component-usage/SKILL.md

@@ -0,0 +1,691 @@
+---
+name: turknet-onehub-component-usage
+description: Use ONLY when generating Material UI component code with @turknet/onehub theme. Enforces correct component usage, variant/size/color rules, and prohibits custom components.
+license: MIT
+compatibility: React 18.2+, Next.js 13+
+metadata:
+  theme-version: "2.0+"
+  mui-version: "7.0.0+"
+---
+
+# @turknet/onehub Material UI Component Usage Guide
+
+> **CRITICAL FOR LLM MODELS**: This skill is essential when writing components for projects using `@turknet/onehub`. Read and apply ALL rules.
+
+---
+
+## 🎯 Scope & Trigger
+
+**Use this skill WHEN:**
+- Generating React/TSX components for projects using `@turknet/onehub` theme
+- Writing code that imports Material UI components (`@mui/material`)
+- Styling buttons, forms, typography, cards, dialogs, tables, or any MUI component
+- Creating layouts with Paper, Container, Box, Stack, Grid
+
+**Do NOT use this skill WHEN:**
+- Using other UI frameworks (Chakra UI, shadcn/ui, Tailwind custom components)
+- Writing non-UI code (hooks, utilities, services, API calls)
+- Dealing with unrelated packages
+
+---
+
+## 📋 Foundation Rules
+
+### Rule 1: Always Use Material UI from @mui/material
+
+```tsx
+// ✅ CORRECT
+import { Button, Typography, TextField } from '@mui/material';
+
+// ❌ WRONG
+import CustomButton from './components/CustomButton';
+import { Button } from 'chakra-ui';
+```
+
+### Rule 2: Only Use Defined Variants, Sizes, and Colors
+
+```tsx
+// ✅ CORRECT: Defined combination
+<Button variant="contained" color="primary" size="medium" />
+
+// ❌ WRONG: Non-existent variant/size/color
+<Button variant="gradient" size="huge" color="unknown" />
+```
+
+### Rule 3: Never Write Custom Components or Inline Styles
+
+```tsx
+// ✅ CORRECT
+<Button variant="contained" color="error" size="large">
+  Delete
+</Button>
+
+// ❌ WRONG: Custom component
+function CustomButton() {
+  return <div style={{backgroundColor: '#FF0000', ...}}>Custom</div>;
+}
+
+// ❌ WRONG: Inline styles
+<Button style={{backgroundColor: '#FF0000', padding: '20px'}}>
+  Button
+</Button>
+```
+
+### Rule 4: Use Theme Color Palettes Correctly
+
+```tsx
+// ✅ CORRECT: Use neutral, brand, danger
+<Button color="primary" />              // brand colors
+<TextField color="neutral" />           // neutral colors
+<Button color="error" />                // danger colors
+
+// ❌ WRONG: Direct palette access
+<div style={{backgroundColor: theme.palette.shared.red[3]}}>
+  Custom
+</div>
+```
+
+**Note**: Shared colors (red, green, orange, etc.) are only for custom components when design demands them.
+
+### Rule 5: Always Use Typography Variants
+
+```tsx
+// ✅ CORRECT: Use customized variants
+<Typography variant="display.lg.bold">Page Title</Typography>
+<Typography variant="text.md.semibold">Section Heading</Typography>
+<Typography variant="text.sm.regular">Body text</Typography>
+
+// ❌ WRONG: HTML tags or divs
+<h1>Page Title</h1>
+<p>Body text</p>
+<div>Unstyled content</div>
+```
+
+---
+
+## 🎨 Theme System Reference
+
+### Color Palettes
+
+The theme has three main palettes:
+
+```
+palette:
+  ├── neutral       → Default UI (backgrounds, text, borders)
+  ├── brand         → Primary actions (blue tones in light, modified in dark)
+  ├── danger        → Error/destructive (red tones)
+  └── shared        → Base colors (red, green, orange, yellow, purple, pink, cyan, lime)
+```
+
+### Valid Component Color Combinations
+
+| Component | Valid Colors | Default |
+|---|---|---|
+| **Button** | primary, secondary, error | primary |
+| **TextField** | neutral, brand, danger | neutral |
+| **Select** | neutral, brand, danger | neutral (via TextField) |
+| **Checkbox** | primary, error | primary |
+| **Radio** | primary, error | primary |
+| **Switch** | primary, error | primary |
+| **Chip** | primary, secondary, error | primary |
+| **Alert** | success, warning, error, info | - |
+| **Badge** | primary, secondary, error, success, warning, info | - |
+
+### Typography Variants
+
+**Display Variants** (for headings):
+```
+display.xl2.{regular|medium|semibold|bold}    → 72px
+display.xl.{regular|medium|semibold|bold}     → 60px
+display.lg.{regular|medium|semibold|bold}     → 48px
+display.md.{regular|medium|semibold|bold}     → 36px
+display.sm.{regular|medium|semibold|bold}     → 30px
+display.xs.{regular|medium|semibold|bold}     → 24px
+```
+
+**Text Variants** (for body/UI text):
+```
+text.xl.{regular|medium|semibold|bold}        → 20px
+text.lg.{regular|medium|semibold|bold}        → 18px
+text.md.{regular|medium|semibold|bold}        → 16px
+text.sm.{regular|medium|semibold|bold}        → 14px
+text.xs.{regular|medium|semibold|bold}        → 12px
+```
+
+**Usage:**
+```tsx
+// Main page heading
+<Typography variant="display.lg.bold">Dashboard</Typography>
+
+// Section heading
+<Typography variant="display.md.semibold">Recent Activity</Typography>
+
+// Emphasized body text
+<Typography variant="text.md.semibold">Important notice</Typography>
+
+// Regular body text
+<Typography variant="text.md.regular">Description text</Typography>
+
+// Small helper text
+<Typography variant="text.sm.regular">Helper information</Typography>
+```
+
+### Component Size Options
+
+| Component | Valid Sizes |
+|---|---|
+| **Button** | extra-small, small, medium, large, extra-large |
+| **TextField** | small, medium, large |
+| **Select** | small, medium, large |
+| **Checkbox** | small, medium |
+| **Radio** | small, medium |
+| **Switch** | small, medium |
+| **Slider** | small, medium |
+| **Chip** | small, medium |
+| **Avatar** | small, medium, large |
+| **Pagination** | small, medium |
+| **Table** | small, medium |
+
+### Paper Elevation Levels
+
+Use `elevation` prop with values **0-24**:
+
+```tsx
+<Paper elevation={0}>Flat (no shadow)</Paper>
+<Paper elevation={4}>Standard card</Paper>
+<Paper elevation={8}>Dialog level</Paper>
+<Paper elevation={16}>Modal level</Paper>
+<Paper elevation={24}>Highest level (Tooltip, Popper)</Paper>
+```
+
+---
+
+## 📦 Component Structure & Sub-Components
+
+### Form Components with Sub-Components
+
+```tsx
+// TextField (includes InputBase, InputLabel, FilledInput, OutlinedInput)
+<TextField
+  label="Email"
+  variant="outlined"          // filled, outlined, standard
+  color="neutral"             // neutral, brand, danger
+  size="medium"               // small, medium, large
+  type="email"
+  fullWidth
+  helperText="Required field"
+  error={hasError}
+/>
+
+// Select with MenuItem
+<Select color="neutral" size="medium">
+  <MenuItem value="opt1">Option 1</MenuItem>
+  <MenuItem value="opt2">Option 2</MenuItem>
+</Select>
+
+// FormControl with multiple controls
+<FormControl>
+  <FormLabel>Choose one</FormLabel>
+  <RadioGroup>
+    <FormControlLabel control={<Radio />} label="Option A" />
+    <FormControlLabel control={<Radio />} label="Option B" />
+  </RadioGroup>
+</FormControl>
+```
+
+### Container Components with Children
+
+```tsx
+// Card with sections
+<Card>
+  <CardHeader title="Title" subheader="Subtitle" />
+  <CardContent>
+    <Typography variant="text.md.regular">Content</Typography>
+  </CardContent>
+  <CardActions>
+    <Button>Action</Button>
+  </CardActions>
+</Card>
+
+// Dialog structure
+<Dialog open={open} onClose={handleClose}>
+  <DialogTitle>Title</DialogTitle>
+  <DialogContent>
+    <Typography variant="text.md.regular">Content</Typography>
+  </DialogContent>
+  <DialogActions>
+    <Button variant="text">Cancel</Button>
+    <Button variant="contained">Confirm</Button>
+  </DialogActions>
+</Dialog>
+```
+
+### List Components with Child Elements
+
+```tsx
+// Properly composed List
+<List>
+  <ListItem>
+    <ListItemIcon><StarIcon /></ListItemIcon>
+    <ListItemText 
+      primary="Main text"
+      secondary="Secondary text"
+    />
+  </ListItem>
+  <Divider />
+  <ListItemButton>
+    <ListItemText primary="Clickable item" />
+  </ListItemButton>
+</List>
+```
+
+### Table Structure
+
+```tsx
+// Complete Table
+<Table>
+  <TableHead>
+    <TableRow>
+      <TableCell>Column 1</TableCell>
+      <TableCell>Column 2</TableCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>Data 1</TableCell>
+      <TableCell>Data 2</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+---
+
+## ✅ Component-Specific Guidelines
+
+### Button
+
+```tsx
+// All valid combinations
+<Button variant="contained" color="primary" size="medium" />
+<Button variant="outlined" color="secondary" size="small" />
+<Button variant="text" color="error" size="large" />
+<Button variant="contained" color="primary" size="extra-small" />
+<Button variant="contained" color="primary" size="extra-large" />
+
+// With icons
+<Button 
+  startIcon={<DeleteIcon />}
+  variant="contained" 
+  color="error"
+>
+  Delete
+</Button>
+
+// Icon only
+<Button variant="text" color="primary">
+  <SearchIcon />
+</Button>
+```
+
+### TextField & Related Inputs
+
+```tsx
+// Standard TextField
+<TextField
+  label="Full Name"
+  variant="outlined"
+  color="neutral"
+  size="medium"
+  fullWidth
+/>
+
+// With error state
+<TextField
+  label="Email"
+  color="danger"
+  error
+  helperText="Invalid email format"
+/>
+
+// With icons/adornments
+<TextField
+  InputProps={{
+    startAdornment: <InputAdornment position="start"><SearchIcon /></InputAdornment>
+  }}
+/>
+
+// Multiline
+<TextField
+  label="Description"
+  multiline
+  rows={4}
+  variant="outlined"
+  color="neutral"
+/>
+```
+
+### Select & MenuItem
+
+```tsx
+// Simple select
+<TextField
+  select
+  label="Category"
+  variant="outlined"
+  color="neutral"
+  size="medium"
+>
+  <MenuItem value="cat1">Category 1</MenuItem>
+  <MenuItem value="cat2">Category 2</MenuItem>
+</TextField>
+
+// With disabled options
+<TextField
+  select
+  label="Status"
+  variant="outlined"
+  color="neutral"
+>
+  <MenuItem value="active">Active</MenuItem>
+  <MenuItem value="inactive" disabled>Inactive</MenuItem>
+</TextField>
+```
+
+### Alert & Severity
+
+```tsx
+// All severity options
+<Alert severity="success">Success message</Alert>
+<Alert severity="warning">Warning message</Alert>
+<Alert severity="error">Error message</Alert>
+<Alert severity="info">Info message</Alert>
+
+// With custom title
+<Alert severity="error">
+  <AlertTitle>Error</AlertTitle>
+  Detailed error message
+</Alert>
+```
+
+### Chip & Badge
+
+```tsx
+// Different Chip styles
+<Chip label="Tag" variant="filled" color="primary" />
+<Chip label="Tag" variant="outlined" color="secondary" />
+<Chip label="Removable" onDelete={() => {}} />
+<Chip icon={<StarIcon />} label="Favorite" />
+
+// Badge
+<Badge badgeContent={4} color="error">
+  <MailIcon />
+</Badge>
+```
+
+### Paper & Elevation
+
+```tsx
+// Different elevation levels
+<Paper elevation={0}>Flat background</Paper>
+<Paper elevation={4}>Standard card</Paper>
+<Paper elevation={8}>Elevated section</Paper>
+<Paper elevation={16}>Modal-level elevation</Paper>
+<Paper elevation={24}>Tooltip-level elevation</Paper>
+```
+
+---
+
+## 🚨 Common Mistakes to Avoid
+
+### Mistake 1: Custom Button Component
+```tsx
+// ❌ WRONG
+function MyButton() {
+  return (
+    <button 
+      style={{
+        backgroundColor: '#2563eb',
+        padding: '10px 20px',
+        borderRadius: '4px'
+      }}
+    >
+      Custom Button
+    </button>
+  );
+}
+
+// ✅ CORRECT
+<Button variant="contained" color="primary" size="medium">
+  Standard Button
+</Button>
+```
+
+### Mistake 2: Non-existent Variants
+```tsx
+// ❌ WRONG
+<Button variant="gradient" size="huge" color="blue" />
+
+// ✅ CORRECT
+<Button variant="contained" size="large" color="primary" />
+```
+
+### Mistake 3: Missing Typography Variant
+```tsx
+// ❌ WRONG
+<div style={{fontSize: '20px', fontWeight: 'bold'}}>
+  Heading
+</div>
+
+// ✅ CORRECT
+<Typography variant="display.lg.bold">
+  Heading
+</Typography>
+```
+
+### Mistake 4: Inline Styles
+```tsx
+// ❌ WRONG
+<Button style={{backgroundColor: '#FF0000', padding: '20px'}}>
+  Delete
+</Button>
+
+// ✅ CORRECT
+<Button variant="contained" color="error" size="large">
+  Delete
+</Button>
+```
+
+### Mistake 5: Missing Color on TextField
+```tsx
+// ❌ WRONG
+<TextField label="Name" variant="outlined" />
+
+// ✅ CORRECT
+<TextField 
+  label="Name" 
+  variant="outlined" 
+  color="neutral"  // Required!
+  size="medium"
+/>
+```
+
+### Mistake 6: HTML Tags Instead of Typography
+```tsx
+// ❌ WRONG
+<h1>Page Title</h1>
+<h2>Section Title</h2>
+<p>Body text</p>
+
+// ✅ CORRECT
+<Typography variant="display.lg.bold">Page Title</Typography>
+<Typography variant="display.md.semibold">Section Title</Typography>
+<Typography variant="text.md.regular">Body text</Typography>
+```
+
+### Mistake 7: Shared Colors in Components
+```tsx
+// ❌ WRONG: Using shared colors in Button (should only be in custom components)
+<Button style={{backgroundColor: theme.palette.shared.purple[3]}}>
+  Button
+</Button>
+
+// ✅ CORRECT: Using button color props
+<Button color="primary">
+  Button
+</Button>
+
+// ✅ CORRECT: Shared colors ONLY in custom component when needed
+const CustomStatusBadge = () => (
+  <div style={{backgroundColor: theme.palette.shared.green[3]}}>
+    Active
+  </div>
+);
+```
+
+---
+
+## 🔍 Before Writing Component Code
+
+### Checklist
+
+- [ ] Does the component use only Material UI from `@mui/material`?
+- [ ] Are all variant/size/color combinations defined in this guide?
+- [ ] Did I use Typography variants instead of HTML tags?
+- [ ] Did I avoid inline styles and custom components?
+- [ ] For form components, did I specify the `color` prop?
+- [ ] For nested components (Card, List, Table), did I use proper sub-components?
+- [ ] Did I use correct typography sizes for headings vs body text?
+- [ ] Is Paper elevation a value between 0-24?
+
+### Example: Complete Form Component
+
+```tsx
+import { 
+  Box, 
+  TextField, 
+  Button, 
+  Typography, 
+  FormControl, 
+  FormLabel,
+  FormControlLabel,
+  Checkbox,
+  Alert
+} from '@mui/material';
+
+export function LoginForm() {
+  return (
+    <Box component="form" sx={{ maxWidth: 400, mx: 'auto', p: 2 }}>
+      {/* Heading */}
+      <Typography variant="display.md.semibold" sx={{ mb: 3 }}>
+        Sign In
+      </Typography>
+
+      {/* Email field */}
+      <TextField
+        label="Email Address"
+        type="email"
+        variant="outlined"
+        color="neutral"
+        size="medium"
+        fullWidth
+        sx={{ mb: 2 }}
+      />
+
+      {/* Password field */}
+      <TextField
+        label="Password"
+        type="password"
+        variant="outlined"
+        color="neutral"
+        size="medium"
+        fullWidth
+        sx={{ mb: 2 }}
+      />
+
+      {/* Checkbox */}
+      <FormControlLabel
+        control={<Checkbox color="primary" />}
+        label={<Typography variant="text.sm.regular">Remember me</Typography>}
+        sx={{ mb: 3 }}
+      />
+
+      {/* Error alert */}
+      <Alert severity="error" sx={{ mb: 2 }}>
+        Invalid credentials
+      </Alert>
+
+      {/* Submit button */}
+      <Button 
+        variant="contained" 
+        color="primary" 
+        size="large"
+        fullWidth
+      >
+        Sign In
+      </Button>
+    </Box>
+  );
+}
+```
+
+---
+
+## 📚 References
+
+- **@turknet/onehub Package**: https://npm.js/package/@turknet/onehub
+- **LLM Guidelines**: Look for `LLM_GUIDELINES.md` in the package
+- **Usage Examples**: Look for `LLM_EXAMPLES.md` in the package
+- **Material UI Docs**: https://mui.com/material-ui/
+- **Material UI API**: https://mui.com/material-ui/api/
+
+---
+
+## ⚙️ Integration with Your Project
+
+### 1. Install the Theme Package
+
+```bash
+yarn add @turknet/onehub
+```
+
+### 2. Apply Theme Provider
+
+```tsx
+// pages/_app.tsx or app layout
+import { ThemeProvider } from '@mui/material/styles';
+import theme from '@turknet/onehub/theme';
+import '@turknet/onehub/fonts.css';
+
+export default function App({ Component, pageProps }) {
+  return (
+    <ThemeProvider theme={theme}>
+      <Component {...pageProps} />
+    </ThemeProvider>
+  );
+}
+```
+
+### 3. Start Using Components
+
+```tsx
+import { Button, Typography, TextField } from '@mui/material';
+
+export function MyComponent() {
+  return (
+    <>
+      <Typography variant="display.lg.bold">Title</Typography>
+      <TextField variant="outlined" color="neutral" />
+      <Button variant="contained" color="primary">
+        Submit
+      </Button>
+    </>
+  );
+}
+```
+
+---
+
+**Last Updated**: May 2026  
+**Skill Version**: 1.0  
+**Theme Version**: 2.0+