@turk.net/mui 3.0.7 → 3.0.8

package/LLM_EXAMPLES.md

@@ -1,33 +1,33 @@
-# LLM Examples - Doğru vs Yanlış Kullanımlar
+# LLM Examples — Correct vs. Incorrect Usage
 
-Bu belge Material UI bileşenlerinin `@turknet/onehub` tema paketi kurallarına göre doğru ve yanlış kullanımlarını gösterir.
+This document demonstrates correct and incorrect usage of Material UI components according to the `@turknet/onehub` theme package rules.
 
 ---
 
-## 📚 İçindekiler
+## Table of Contents
 
-1. [Button Bileşeni](#button-bileşeni)
-2. [TextField Bileşeni](#textfield-bileşeni)
-3. [Typography Bileşeni](#typography-bileşeni)
+1. [Button Component](#button-component)
+2. [TextField Component](#textfield-component)
+3. [Typography Component](#typography-component)
 4. [Select & MenuItem](#select--menuitem)
 5. [Checkbox, Radio, Switch](#checkbox-radio-switch)
 6. [Alert & Snackbar](#alert--snackbar)
-7. [Card Bileşeni](#card-bileşeni)
-8. [Dialog Bileşeni](#dialog-bileşeni)
-9. [List Bileşeni](#list-bileşeni)
-10. [Table Bileşeni](#table-bileşeni)
+7. [Card Component](#card-component)
+8. [Dialog Component](#dialog-component)
+9. [List Component](#list-component)
+10. [Table Component](#table-component)
 11. [Paper & Elevation](#paper--elevation)
 12. [Chip & Badge](#chip--badge)
-13. [Ortak Hatalar](#ortak-hatalar)
+13. [Common Mistakes](#common-mistakes)
 
 ---
 
-## Button Bileşeni
+## Button Component
 
-### ✅ Doğru Kullanımlar
+### ✅ Correct Usage
 
 ```tsx
-// ✅ Temel button
+// ✅ Basic button
 import { Button } from '@mui/material';
 
 <Button variant="contained" color="primary" size="medium">
@@ -44,7 +44,7 @@ import { Button } from '@mui/material';
   Sil
 </Button>
 
-// ✅ Extra-small button (tema özel)
+// ✅ Extra-small button (theme-specific)
 <Button variant="contained" color="primary" size="extra-small">
   Kısa
 </Button>
@@ -54,7 +54,7 @@ import { Button } from '@mui/material';
   Büyük
 </Button>
 
-// ✅ Button ikonu ile
+// ✅ Button with icon
 import { DeleteIcon } from '@turknet/onehub/icons';
 
 <Button 
@@ -86,25 +86,25 @@ import { DeleteIcon } from '@turknet/onehub/icons';
 </Button>
 ```
 
-### ❌ Yanlış Kullanımlar
+### ❌ Incorrect Usage
 
 ```tsx
-// ❌ Tanımlı olmayan variant
+// ❌ Undefined variant — You MUST ONLY use: "contained", "outlined", "text"
 <Button variant="gradient" color="primary">
   Gradient Button
 </Button>
 
-// ❌ Tanımlı olmayan size
+// ❌ Undefined size — You MUST ONLY use: "extra-small", "small", "medium", "large", "extra-large"
 <Button size="huge">
   Buton
 </Button>
 
-// ❌ Tanımlı olmayan color
+// ❌ Undefined color — You MUST ONLY use: "primary", "secondary", "error", "info", "success", "warning"
 <Button color="unknown">
   Buton
 </Button>
 
-// ❌ Custom button component yazma
+// ❌ Custom button component — You MUST NEVER write custom button components
 function CustomButton() {
   return (
     <div style={{
@@ -120,7 +120,7 @@ function CustomButton() {
   );
 }
 
-// ❌ Inline style override
+// ❌ Inline style override — You MUST NEVER use the `style` prop
 <Button 
   variant="contained" 
   color="primary"
@@ -129,7 +129,7 @@ function CustomButton() {
   Renkli Buton
 </Button>
 
-// ❌ sx prop ile tema kurallarını ezmek
+// ❌ Overriding theme rules with sx — You MUST NEVER override theme styling via `sx`
 <Button 
   variant="contained" 
   sx={{
@@ -143,14 +143,14 @@ function CustomButton() {
 
 ---
 
-## TextField Bileşeni
+## TextField Component
 
-### ✅ Doğru Kullanımlar
+### ✅ Correct Usage
 
 ```tsx
 import { TextField } from '@mui/material';
 
-// ✅ Temel kullanım
+// ✅ Basic usage
 <TextField
   label="Ad Soyadı"
   variant="outlined"
@@ -159,7 +159,7 @@ import { TextField } from '@mui/material';
   fullWidth
 />
 
-// ✅ Brand rengiyle
+// ✅ With brand color
 <TextField
   label="Email"
   variant="outlined"
@@ -168,7 +168,7 @@ import { TextField } from '@mui/material';
   type="email"
 />
 
-// ✅ Hata durumu
+// ✅ Error state
 <TextField
   label="Şifre"
   variant="outlined"
@@ -179,7 +179,7 @@ import { TextField } from '@mui/material';
   helperText="Şifre en az 8 karakter olmalıdır"
 />
 
-// ✅ Yardımcı metin (başarı)
+// ✅ Helper text (success)
 <TextField
   label="Username"
   variant="outlined"
@@ -188,7 +188,7 @@ import { TextField } from '@mui/material';
   helperText="6-20 karakter arasında"
 />
 
-// ✅ Placeholder ile
+// ✅ With placeholder
 <TextField
   variant="outlined"
   color="neutral"
@@ -196,7 +196,7 @@ import { TextField } from '@mui/material';
   placeholder="Ara..."
 />
 
-// ✅ Icon/Adornment ile
+// ✅ With icon/adornment
 import { SearchIcon } from '@turknet/onehub/icons';
 import { InputAdornment } from '@mui/material';
 
@@ -236,30 +236,30 @@ import { InputAdornment } from '@mui/material';
 />
 ```
 
-### ❌ Yanlış Kullanımlar
+### ❌ Incorrect Usage
 
 ```tsx
-// ❌ color prop'u olmadan
+// ❌ Missing `color` prop — You MUST always provide a color prop. Use "neutral" or "brand".
 <TextField
   label="Ad"
   variant="outlined"
 />
-// ✅ DOĞRU: color="neutral" veya color="brand"
+// ✅ CORRECT: color="neutral" or color="brand"
 
-// ❌ Tanımlı olmayan color
+// ❌ Undefined color — You MUST ONLY use: "neutral", "brand", "danger", "success"
 <TextField
   label="Ad"
   variant="outlined"
   color="unknown"
 />
 
-// ❌ Tanımlı olmayan variant
+// ❌ Undefined variant — You MUST ONLY use: "outlined", "filled", "standard"
 <TextField
   label="Ad"
   variant="gradient"
 />
 
-// ❌ Custom input component
+// ❌ Custom input component — You MUST NEVER write custom input components
 function CustomInput() {
   return (
     <input 
@@ -273,13 +273,13 @@ function CustomInput() {
   );
 }
 
-// ❌ Inline style
+// ❌ Inline style — You MUST NEVER use the `style` prop
 <TextField
   label="Ad"
   style={{backgroundColor: '#f0f0f0'}}
 />
 
-// ❌ HTML input elementi
+// ❌ HTML input element — You MUST NEVER use raw HTML input elements
 <input 
   type="text" 
   placeholder="Ad" 
@@ -289,59 +289,59 @@ function CustomInput() {
 
 ---
 
-## Typography Bileşeni
+## Typography Component
 
-### ✅ Doğru Kullanımlar
+### ✅ Correct Usage
 
 ```tsx
 import { Typography } from '@mui/material';
 
-// ✅ Ana başlık (sayfanın en üst başlığı)
+// ✅ Main heading (top-level page heading)
 <Typography variant="display.lg.bold">
   Sayfanın Başlığı
 </Typography>
 
-// ✅ Alt başlık
+// ✅ Subheading
 <Typography variant="display.md.semibold">
   Alt Başlık
 </Typography>
 
-// ✅ Bölüm başlığı
+// ✅ Section heading
 <Typography variant="display.sm.semibold">
   Bölüm Başlığı
 </Typography>
 
-// ✅ Normal metin
+// ✅ Body text
 <Typography variant="text.md.regular">
   Gövde metni, açıklamalar, normal içerik
 </Typography>
 
-// ✅ Vurgu yapmak gerekirse
+// ✅ Emphasized text (when emphasis is needed)
 <Typography variant="text.md.semibold">
   Önemli metin
 </Typography>
 
-// ✅ Büyük vurgu
+// ✅ Strong emphasis
 <Typography variant="text.md.bold">
   Çok Önemli Metin
 </Typography>
 
-// ✅ Küçük yardımcı metin
+// ✅ Small helper text
 <Typography variant="text.sm.regular">
   Yardımcı bilgi, açıklama
 </Typography>
 
-// ✅ Çok küçük metin
+// ✅ Extra-small text
 <Typography variant="text.xs.regular">
   Footer metin, bildiri
 </Typography>
 
-// ✅ Tek satır kıs_ma
+// ✅ Single-line truncation
 <Typography variant="text.md.regular" noWrap>
   Çok uzun metin tek satırda kısaltılır...
 </Typography>
 
-// ✅ Birden fazla satırda kısma
+// ✅ Multi-line truncation
 <Typography 
   variant="text.md.regular"
   sx={{
@@ -355,38 +355,38 @@ import { Typography } from '@mui/material';
 </Typography>
 ```
 
-### ❌ Yanlış Kullanımlar
+### ❌ Incorrect Usage
 
 ```tsx
-// ❌ Material UI varsayılan variant'ları
+// ❌ Material UI default variants — You MUST NEVER use default MUI variants. Use theme-specific variants ONLY.
 <Typography variant="h1">
   Başlık
 </Typography>
-// ✅ DOĞRU: variant="display.lg.bold"
+// ✅ CORRECT: variant="display.lg.bold"
 
 <Typography variant="body1">
   Metin
 </Typography>
-// ✅ DOĞRU: variant="text.md.regular"
+// ✅ CORRECT: variant="text.md.regular"
 
-// ❌ HTML tag'ı kullanma
+// ❌ HTML heading/paragraph tags — You MUST NEVER use raw HTML tags for text
 <h1>Başlık</h1>
 <h2>Alt Başlık</h2>
 <p>Metin</p>
-// ✅ DOĞRU: Typography bileşeni kullan
+// ✅ CORRECT: Use Typography component
 
-// ❌ Div ile metin
+// ❌ Div for text — You MUST NEVER use a <div> for plain text content
 <div>Bu sadece metin</div>
-// ✅ DOĞRU: <Typography variant="text.md.regular">
+// ✅ CORRECT: <Typography variant="text.md.regular">
 
-// ❌ Inline style
+// ❌ Inline style — You MUST NEVER use the `style` prop for typography
 <Typography 
   style={{fontSize: '20px', fontWeight: 'bold'}}
 >
   Metin
 </Typography>
 
-// ❌ Tanımlı olmayan variant
+// ❌ Undefined variant — You MUST ONLY use variants from the theme's Untitled UI design system
 <Typography variant="super-large-bold">
   Metin
 </Typography>
@@ -396,12 +396,12 @@ import { Typography } from '@mui/material';
 
 ## Select & MenuItem
 
-### ✅ Doğru Kullanımlar
+### ✅ Correct Usage
 
 ```tsx
 import { Select, MenuItem, FormControl, InputLabel } from '@mui/material';
 
-// ✅ Temel Select
+// ✅ Basic Select
 <FormControl fullWidth>
   <InputLabel>Kategori</InputLabel>
   <Select 
@@ -415,7 +415,7 @@ import { Select, MenuItem, FormControl, InputLabel } from '@mui/material';
   </Select>
 </FormControl>
 
-// ✅ TextField'i Select ile
+// ✅ TextField as Select
 <TextField
   select
   label="Ülke"
@@ -462,16 +462,16 @@ import { Select, MenuItem, FormControl, InputLabel } from '@mui/material';
 </TextField>
 ```
 
-### ❌ Yanlış Kullanımlar
+### ❌ Incorrect Usage
 
 ```tsx
-// ❌ HTML select elementi
+// ❌ HTML select element — You MUST NEVER use raw HTML <select> elements
 <select>
   <option>Seçenek 1</option>
   <option>Seçenek 2</option>
 </select>
 
-// ❌ Custom Select component
+// ❌ Custom Select component — You MUST NEVER write custom Select components
 function CustomSelect() {
   return (
     <div 
@@ -486,12 +486,12 @@ function CustomSelect() {
   );
 }
 
-// ❌ MenuItem olmadan options
+// ❌ Select without MenuItem — You MUST always wrap options in MenuItem components
 <Select color="neutral">
   {/* Missing MenuItem */}
 </Select>
 
-// ❌ Tanımlı olmayan color
+// ❌ Undefined color — You MUST ONLY use: "neutral", "brand"
 <Select color="unknown">
   <MenuItem value="option1">Seçenek 1</MenuItem>
 </Select>
@@ -501,7 +501,7 @@ function CustomSelect() {
 
 ## Checkbox, Radio, Switch
 
-### ✅ Doğru Kullanımlar
+### ✅ Correct Usage
 
 ```tsx
 import { 
@@ -515,18 +515,18 @@ import {
   RadioGroup 
 } from '@mui/material';
 
-// ✅ Temel Checkbox
+// ✅ Basic Checkbox
 <Checkbox 
   color="primary"
 />
 
-// ✅ Checkbox ile label
+// ✅ Checkbox with label — You MUST use FormControlLabel
 <FormControlLabel
   control={<Checkbox color="primary" />}
   label="Şartları Kabul Ediyorum"
 />
 
-// ✅ Checkbox grubu
+// ✅ Checkbox group
 <FormControl>
   <FormLabel>Tercihler</FormLabel>
   <FormGroup>
@@ -541,17 +541,17 @@ import {
   </FormGroup>
 </FormControl>
 
-// ✅ Temel Radio
+// ✅ Basic Radio
 <Radio color="primary" />
 
-// ✅ Radio ile label
+// ✅ Radio with label
 <FormControlLabel
   value="option1"
   control={<Radio color="primary" />}
   label="Seçenek 1"
 />
 
-// ✅ Radio grubu
+// ✅ Radio group
 <FormControl>
   <FormLabel>Tema Seçimi</FormLabel>
   <RadioGroup defaultValue="light">
@@ -568,10 +568,10 @@ import {
   </RadioGroup>
 </FormControl>
 
-// ✅ Temel Switch
+// ✅ Basic Switch
 <Switch color="primary" />
 
-// ✅ Switch ile label
+// ✅ Switch with label
 <FormControlLabel
   control={<Switch color="primary" />}
   label="Aktiv Et"
@@ -584,64 +584,64 @@ import {
 />
 ```
 
-### ❌ Yanlış Kullanımlar
+### ❌ Incorrect Usage
 
 ```tsx
-// ❌ HTML input'lar
+// ❌ HTML inputs — You MUST NEVER use raw HTML <input type="checkbox"> or <input type="radio">
 <input type="checkbox" />
 <input type="radio" />
 
-// ❌ Tanımlı olmayan color
+// ❌ Undefined color — You MUST ONLY use: "primary", "secondary", "error", "info", "success", "warning"
 <Checkbox color="unknown" />
 <Radio color="unknown" />
 <Switch color="unknown" />
 
-// ❌ FormControlLabel olmadan
+// ❌ Missing FormControlLabel — You MUST use FormControlLabel to display a label alongside the control
 <Checkbox color="primary" />
-// ✅ DOĞRU: FormControlLabel ile label'i göster
+// ✅ CORRECT: Use FormControlLabel to show the label
 ```
 
 ---
 
 ## Alert & Snackbar
 
-### ✅ Doğru Kullanımlar
+### ✅ Correct Usage
 
 ```tsx
 import { Alert, Snackbar, AlertTitle } from '@mui/material';
 
-// ✅ Başarılı alert
+// ✅ Success alert
 <Alert severity="success">
   İşlem başarıyla tamamlandı!
 </Alert>
 
-// ✅ Uyarı alert
+// ✅ Warning alert
 <Alert severity="warning">
   Uyarı: Dikkat edin!
 </Alert>
 
-// ✅ Hata alert
+// ✅ Error alert
 <Alert severity="error">
   Hata: İşlem başarısız oldu!
 </Alert>
 
-// ✅ Bilgi alert
+// ✅ Info alert
 <Alert severity="info">
   Bilgi: Yeni feature eklenmiştir.
 </Alert>
 
-// ✅ Alert title ile
+// ✅ Alert with title — You MUST use AlertTitle for titled alerts
 <Alert severity="error">
   <AlertTitle>Hata</AlertTitle>
   Lütfen tüm alanları doldurunuz!
 </Alert>
 
-// ✅ Alert icon olmadan
+// ✅ Alert without icon
 <Alert severity="success" icon={false}>
   Başarılı
 </Alert>
 
-// ✅ Snackbar ile temporary notification
+// ✅ Snackbar for temporary notifications
 const [open, setOpen] = React.useState(false);
 
 <Snackbar
@@ -655,20 +655,20 @@ const [open, setOpen] = React.useState(false);
 </Snackbar>
 ```
 
-### ❌ Yanlış Kullanımlar
+### ❌ Incorrect Usage
 
 ```tsx
-// ❌ Severity olmadan
+// ❌ Missing severity — You MUST always provide a `severity` prop
 <Alert>
   Sadece bir mesaj
 </Alert>
 
-// ❌ Tanımlı olmayan severity
+// ❌ Undefined severity — You MUST ONLY use: "success", "warning", "error", "info"
 <Alert severity="unknown">
   Mesaj
 </Alert>
 
-// ❌ Custom alert component
+// ❌ Custom alert component — You MUST NEVER write custom alert components
 function CustomAlert() {
   return (
     <div style={{
@@ -685,9 +685,9 @@ function CustomAlert() {
 
 ---
 
-## Card Bileşeni
+## Card Component
 
-### ✅ Doğru Kullanımlar
+### ✅ Correct Usage
 
 ```tsx
 import { 
@@ -699,7 +699,7 @@ import {
   Typography
 } from '@mui/material';
 
-// ✅ Temel Card
+// ✅ Basic Card
 <Card>
   <CardContent>
     <Typography variant="text.md.regular">
@@ -708,7 +708,7 @@ import {
   </CardContent>
 </Card>
 
-// ✅ Card tam yapı
+// ✅ Full Card structure — You MUST use CardHeader, CardContent, and CardActions sub-components
 <Card>
   <CardHeader 
     title="Kart Başlığı"
@@ -729,7 +729,7 @@ import {
   </CardActions>
 </Card>
 
-// ✅ Card elevation ile
+// ✅ Card with elevation
 <Card elevation={4}>
   <CardContent>
     <Typography variant="display.sm.semibold">
@@ -739,10 +739,10 @@ import {
 </Card>
 ```
 
-### ❌ Yanlış Kullanımlar
+### ❌ Incorrect Usage
 
 ```tsx
-// ❌ Div ile card
+// ❌ Div as card — You MUST NEVER use a raw <div> as a card
 <div style={{
   padding: '20px',
   border: '1px solid #ddd',
@@ -751,7 +751,7 @@ import {
   Özel Kart
 </div>
 
-// ❌ CardHeader olmadan başlık
+// ❌ Header without CardHeader — You MUST use CardHeader for card headings
 <Card>
   <div style={{padding: '16px', borderBottom: '1px solid #ddd'}}>
     <h2>Başlık</h2>
@@ -762,9 +762,9 @@ import {
 
 ---
 
-## Dialog Bileşeni
+## Dialog Component
 
-### ✅ Doğru Kullanımlar
+### ✅ Correct Usage
 
 ```tsx
 import { 
@@ -776,7 +776,7 @@ import {
   Typography
 } from '@mui/material';
 
-// ✅ Temel Dialog
+// ✅ Basic Dialog — You MUST use DialogTitle, DialogContent, and DialogActions sub-components
 const [open, setOpen] = React.useState(false);
 
 <Dialog open={open} onClose={() => setOpen(false)}>
@@ -796,7 +796,7 @@ const [open, setOpen] = React.useState(false);
   </DialogActions>
 </Dialog>
 
-// ✅ Silme onay dialogu
+// ✅ Delete confirmation dialog
 <Dialog open={open} onClose={() => setOpen(false)}>
   <DialogTitle>Silme Onayı</DialogTitle>
   <DialogContent>
@@ -818,7 +818,7 @@ const [open, setOpen] = React.useState(false);
   </DialogActions>
 </Dialog>
 
-// ✅ Geniş dialog
+// ✅ Wide dialog
 <Dialog 
   open={open} 
   onClose={() => setOpen(false)}
@@ -843,10 +843,10 @@ const [open, setOpen] = React.useState(false);
 </Dialog>
 ```
 
-### ❌ Yanlış Kullanımlar
+### ❌ Incorrect Usage
 
 ```tsx
-// ❌ Custom modal dialog
+// ❌ Custom modal dialog — You MUST NEVER build custom modal/dialog implementations
 function CustomDialog() {
   return (
     <div style={{
@@ -871,7 +871,7 @@ function CustomDialog() {
   );
 }
 
-// ❌ Dialog yapısı olmadan title/content/actions
+// ❌ Dialog without structured sub-components — You MUST use DialogTitle, DialogContent, and DialogActions
 <Dialog open={open}>
   Tüm içerik bir div'de
 </Dialog>
@@ -879,9 +879,9 @@ function CustomDialog() {
 
 ---
 
-## List Bileşeni
+## List Component
 
-### ✅ Doğru Kullanımlar
+### ✅ Correct Usage
 
 ```tsx
 import { 
@@ -894,7 +894,7 @@ import {
 } from '@mui/material';
 import { StarIcon } from '@turknet/onehub/icons';
 
-// ✅ Temel List
+// ✅ Basic List
 <List>
   <ListItem>
     <ListItemText primary="Öğe 1" />
@@ -904,7 +904,7 @@ import { StarIcon } from '@turknet/onehub/icons';
   </ListItem>
 </List>
 
-// ✅ List Icon ile
+// ✅ List with icons
 <List>
   <ListItem>
     <ListItemIcon><StarIcon /></ListItemIcon>
@@ -916,7 +916,7 @@ import { StarIcon } from '@turknet/onehub/icons';
   </ListItem>
 </List>
 
-// ✅ List secondary metin ile
+// ✅ List with secondary text
 <List>
   <ListItem>
     <ListItemText 
@@ -932,7 +932,7 @@ import { StarIcon } from '@turknet/onehub/icons';
   </ListItem>
 </List>
 
-// ✅ Tıklanabilir ListItem
+// ✅ Clickable ListItem — You MUST use ListItemButton for clickable items
 <List>
   <ListItemButton>
     <ListItemIcon><StarIcon /></ListItemIcon>
@@ -940,7 +940,7 @@ import { StarIcon } from '@turknet/onehub/icons';
   </ListItemButton>
 </List>
 
-// ✅ Divider ile
+// ✅ With Divider
 <List>
   <ListItem>
     <ListItemText primary="Öğe 1" />
@@ -962,22 +962,22 @@ import { StarIcon } from '@turknet/onehub/icons';
 </List>
 ```
 
-### ❌ Yanlış Kullanımlar
+### ❌ Incorrect Usage
 
 ```tsx
-// ❌ HTML ul/li
+// ❌ HTML ul/li — You MUST NEVER use raw HTML list elements
 <ul>
   <li>Öğe 1</li>
   <li>Öğe 2</li>
 </ul>
 
-// ❌ Div ile list
+// ❌ Div as list — You MUST NEVER use <div> elements to build lists
 <div>
   <div>Öğe 1</div>
   <div>Öğe 2</div>
 </div>
 
-// ❌ ListItemText olmadan
+// ❌ Missing ListItemText — You MUST always use ListItemText for list item content
 <List>
   <ListItem>
     Sadece metin
@@ -987,9 +987,9 @@ import { StarIcon } from '@turknet/onehub/icons';
 
 ---
 
-## Table Bileşeni
+## Table Component
 
-### ✅ Doğru Kullanımlar
+### ✅ Correct Usage
 
 ```tsx
 import { 
@@ -1001,7 +1001,7 @@ import {
   Paper
 } from '@mui/material';
 
-// ✅ Temel tablo
+// ✅ Basic table — You MUST wrap the table in a Paper component
 <Paper>
   <Table>
     <TableHead>
@@ -1026,7 +1026,7 @@ import {
   </Table>
 </Paper>
 
-// ✅ Striped table (renk alternansı)
+// ✅ Striped table (alternating row colors)
 <Table>
   <TableHead>
     <TableRow sx={{backgroundColor: 'neutral.background.2'}}>
@@ -1059,10 +1059,10 @@ import {
 </Table>
 ```
 
-### ❌ Yanlış Kullanımlar
+### ❌ Incorrect Usage
 
 ```tsx
-// ❌ HTML table
+// ❌ HTML table — You MUST NEVER use raw HTML <table> elements
 <table>
   <thead>
     <tr>
@@ -1078,13 +1078,13 @@ import {
   </tbody>
 </table>
 
-// ❌ Div ile table
+// ❌ Div as table — You MUST NEVER build tables using <div> with display:flex
 <div style={{display: 'flex'}}>
   <div style={{flex: 1}}>Ad</div>
   <div style={{flex: 1}}>Email</div>
 </div>
 
-// ❌ TableCell olmadan
+// ❌ Missing TableCell — You MUST always use TableCell inside TableRow
 <Table>
   <TableBody>
     <TableRow>
@@ -1099,7 +1099,7 @@ import {
 
 ## Paper & Elevation
 
-### ✅ Doğru Kullanımlar
+### ✅ Correct Usage
 
 ```tsx
 import { Paper, Typography, Box } from '@mui/material';
@@ -1144,20 +1144,20 @@ import { Paper, Typography, Box } from '@mui/material';
 </Paper>
 ```
 
-### ❌ Yanlış Kullanımlar
+### ❌ Incorrect Usage
 
 ```tsx
-// ❌ Tanımlı olmayan elevation
+// ❌ Undefined elevation — You MUST ONLY use elevation values: 0, 2, 4, 8, 12, 16, 24
 <Paper elevation={100}>
   İçerik
 </Paper>
 
-// ❌ Inline box shadow
+// ❌ Inline box shadow — You MUST NEVER apply boxShadow via inline styles
 <div style={{boxShadow: '0 10px 30px rgba(0,0,0,0.2)'}}>
   Özel gölge
 </div>
 
-// ❌ Paper elevation olmadan shadow
+// ❌ Box shadow via sx instead of Paper — You MUST use Paper with elevation
 <Box sx={{boxShadow: '0 4px 8px rgba(0,0,0,0.1)'}}>
   İçerik
 </Box>
@@ -1167,13 +1167,13 @@ import { Paper, Typography, Box } from '@mui/material';
 
 ## Chip & Badge
 
-### ✅ Doğru Kullanımlar
+### ✅ Correct Usage
 
 ```tsx
 import { Chip, Badge, Avatar } from '@mui/material';
 import { DeleteIcon, StarIcon } from '@turknet/onehub/icons';
 
-// ✅ Temel chip
+// ✅ Basic chip
 <Chip label="Kategori" variant="filled" color="primary" />
 
 // ✅ Outline chip
@@ -1190,7 +1190,7 @@ import { DeleteIcon, StarIcon } from '@turknet/onehub/icons';
   onDelete={() => console.log('deleted')}
 />
 
-// ✅ Icon ile chip
+// ✅ Chip with icon
 <Chip 
   icon={<StarIcon />}
   label="Favori" 
@@ -1198,12 +1198,12 @@ import { DeleteIcon, StarIcon } from '@turknet/onehub/icons';
   color="primary"
 />
 
-// ✅ Temel badge
+// ✅ Basic badge
 <Badge badgeContent={4} color="error">
   <MailIcon />
 </Badge>
 
-// ✅ Avatar ile badge
+// ✅ Badge on Avatar
 <Badge badgeContent={2} color="success">
   <Avatar>A</Avatar>
 </Badge>
@@ -1218,10 +1218,10 @@ import { DeleteIcon, StarIcon } from '@turknet/onehub/icons';
 </Badge>
 ```
 
-### ❌ Yanlış Kullanımlar
+### ❌ Incorrect Usage
 
 ```tsx
-// ❌ Custom chip
+// ❌ Custom chip — You MUST NEVER build custom chip/tag components
 function CustomChip() {
   return (
     <div style={{
@@ -1235,7 +1235,7 @@ function CustomChip() {
   );
 }
 
-// ❌ Span ile badge
+// ❌ Span as badge — You MUST NEVER build custom badge components
 <span style={{
   position: 'relative',
   display: 'inline-block'
@@ -1259,12 +1259,14 @@ function CustomChip() {
 
 ---
 
-## 🚨 Ortak Hatalar
+## Common Mistakes
 
-### Hata 1: Custom Component Yazmak
+### Mistake 1: Writing Custom Components
+
+You MUST NEVER create custom implementations of MUI components. You MUST ONLY use the components provided by `@mui/material`.
 
 ```tsx
-// ❌ YALNLIŞ
+// ❌ INCORRECT
 function CustomButton() {
   return (
     <button style={{...}}>
@@ -1273,7 +1275,7 @@ function CustomButton() {
   );
 }
 
-// ✅ DOĞRU
+// ✅ CORRECT
 import { Button } from '@mui/material';
 
 <Button variant="contained" color="primary">
@@ -1281,43 +1283,49 @@ import { Button } from '@mui/material';
 </Button>
 ```
 
-### Hata 2: Tanımlı Olmayan Props
+### Mistake 2: Undefined Props
+
+You MUST ONLY use props that are defined in the theme. You MUST NEVER pass arbitrary or custom prop values.
 
 ```tsx
-// ❌ YALNLIŞ
+// ❌ INCORRECT
 <Button variant="gradient" size="super-large">
   Buton
 </Button>
 
-// ✅ DOĞRU
+// ✅ CORRECT
 <Button variant="contained" size="extra-large">
   Buton
 </Button>
 ```
 
-### Hata 3: Inline Styles
+### Mistake 3: Inline Styles
+
+You MUST NEVER use the `style` prop on components. You MUST ONLY use the component's defined props (variant, color, size, etc.) to control appearance.
 
 ```tsx
-// ❌ YALNLIŞ
+// ❌ INCORRECT
 <Button style={{backgroundColor: '#FF0000', padding: '20px'}}>
   Kırmızı Buton
 </Button>
 
-// ✅ DOĞRU
+// ✅ CORRECT
 <Button variant="contained" color="error">
   Kırmızı Buton
 </Button>
 ```
 
-### Hata 4: Typography Olmadan Metin
+### Mistake 4: Text Without Typography
+
+You MUST NEVER use raw HTML tags (`<h1>`, `<p>`, `<div>`) for text content. You MUST ONLY use the Typography component.
 
 ```tsx
-// ❌ YALNLIŞ
+// ❌ INCORRECT
 <div>Bu sadece bir metin</div>
 <h1>Başlık</h1>
 <p>Açıklama</p>
 
-// ✅ DOĞRU
+// ✅ CORRECT
 <Typography variant="text.md.regular">
   Bu bir metin
 </Typography>
@@ -1329,20 +1337,22 @@ import { Button } from '@mui/material';
 </Typography>
 ```
 
-### Hata 5: Shared Colors'u Component'lerde Kullanmak
+### Mistake 5: Using Shared Colors on Components
+
+You MUST NOT use `theme.palette.shared` colors directly on MUI components. You MUST ONLY use the component's `color` prop with allowed values. Shared colors MUST ONLY be used in custom (non-MUI) components.
 
 ```tsx
-// ❌ YALNLIŞ: Button'da shared color
+// ❌ INCORRECT: Using shared color on Button
 <Button style={{backgroundColor: theme.palette.shared.green[3]}}>
   Buton
 </Button>
 
-// ✅ DOĞRU: Button'da neutral/brand/danger
+// ✅ CORRECT: Use Button's color prop
 <Button variant="contained" color="primary">
   Buton
 </Button>
 
-// ✅ DOĞRU: Shared colors custom component'lerde
+// ✅ CORRECT: Shared colors are allowed in custom components only
 const CustomBadge = () => (
   <div style={{backgroundColor: theme.palette.shared.purple[3]}}>
     Custom İçerik
@@ -1350,34 +1360,38 @@ const CustomBadge = () => (
 );
 ```
 
-### Hata 6: Elevation Olmadan Shadow
+### Mistake 6: Shadow Without Elevation
+
+You MUST NEVER apply shadows via inline styles or `sx`. You MUST ONLY use the Paper component with the `elevation` prop.
 
 ```tsx
-// ❌ YALNLIŞ
+// ❌ INCORRECT
 <div style={{boxShadow: '0 4px 8px rgba(0,0,0,0.1)'}}>
   İçerik
 </div>
 
-// ✅ DOĞRU
+// ✅ CORRECT
 <Paper elevation={4}>
   İçerik
 </Paper>
 ```
 
-### Hata 7: Material UI Dışı Component Library
+### Mistake 7: Non-Material-UI Component Libraries
+
+You MUST NEVER import components from other UI libraries (Chakra UI, React Bootstrap, etc.). You MUST ONLY import from `@mui/material`.
 
 ```tsx
-// ❌ YALNLIŞ
+// ❌ INCORRECT
 import { Button } from 'chakra-ui';
 import Button from 'react-bootstrap/Button';
 
-// ✅ DOĞRU
+// ✅ CORRECT
 import { Button } from '@mui/material';
 ```
 
 ---
 
-**Referans**: `LLM_GUIDELINES.md` dosyasını okuyunuz daha detaylı bilgi için.
+**Reference**: Read `LLM_GUIDELINES.md` for more detailed information.
 
-**Son Güncelleme**: Mayıs 2026
-**Versiyon**: 2.0+
+**Last Updated**: June 2026
+**Version**: 2.1