@umituz/react-native-design-system 2.6.94 → 2.6.96

package/src/atoms/AtomicCard.README.md

@@ -1,337 +1,448 @@
 # AtomicCard
 
-AtomicCard, React Native için basit ve özelleştirilebilir bir kart container bileşenidir. Material Design 3 prensiplerine uygun olarak tasarlanmıştır.
+A simple and customizable card container component for React Native. Designed following Material Design 3 principles.
 
-## Özellikler
+## Import & Usage
 
-- 🎨 **3 Variant**: Elevated, Outlined, Filled
-- 📦 **4 Padding Seçeneği**: None, Small, Medium, Large
-- 👆 **Pressable**: Tıklanabilir kart desteği
-- 🎯 **Flexible**: İçerik için esnek yapı
-- ♿ **Erişilebilir**: Tam erişilebilirlik desteği
+```typescript
+import { AtomicCard } from 'react-native-design-system/src/atoms/AtomicCard';
+```
+
+**Location:** `src/atoms/AtomicCard.tsx`
 
-## Kurulum
+## Basic Usage
 
 ```tsx
-import { AtomicCard } from 'react-native-design-system';
+<AtomicCard>
+  <AtomicText>Card content</AtomicText>
+</AtomicCard>
 ```
 
-## Temel Kullanım
+## Strategy
 
-```tsx
-import React from 'react';
-import { View, Text } from 'react-native';
-import { AtomicCard } from 'react-native-design-system';
-
-export const BasicExample = () => {
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicCard>
-        <Text>Bu bir kart içeriği</Text>
-      </AtomicCard>
-    </View>
-  );
-};
-```
+**Purpose**: Provide a flexible container component for grouping related content with visual separation.
 
-## Variant'lar
+**When to Use**:
+- Grouping related content (product details, user profiles, settings)
+- Creating clickable list items
+- Displaying information cards (stats, summaries)
+- Building card-based layouts (dashboards, feeds)
+- Highlighting important content sections
 
-```tsx
-<View style={{ gap: 16 }}>
-  {/* Elevated (Varsayılan) */}
-  <AtomicCard variant="elevated">
-    <Text>Elevated Card - Gölge efekti</Text>
-  </AtomicCard>
+**When NOT to Use**:
+- For full-page layouts (use ScreenLayout instead)
+- For simple dividers or borders (use separators)
+- As a replacement for proper modal or sheet components
+- When you need complex card features (actions, menus) - use molecule cards instead
 
-  {/* Outlined */}
-  <AtomicCard variant="outlined">
-    <Text>Outlined Card - Çerçeve efekti</Text>
-  </AtomicCard>
+## Rules
 
-  {/* Filled */}
-  <AtomicCard variant="filled">
-    <Text>Filled Card - Dolgu efekti</Text>
-  </AtomicCard>
-</View>
-```
+### Required
 
-## Padding Seçenekleri
+1. **MUST** have meaningful content inside the card
+2. **ALWAYS** provide padding for content (don't rely on card padding alone)
+3. **SHOULD** use appropriate variant for the context
+4. **MUST** have touch feedback if pressable
+5. **ALWAYS** provide accessibility context if interactive
+6. **SHOULD** maintain consistent spacing within card
+7. **MUST** not nest cards unnecessarily (max 2 levels)
 
-```tsx
-<View style={{ gap: 16 }}>
-  {/* No Padding */}
-  <AtomicCard padding="none">
-    <Text>Padding yok</Text>
-  </AtomicCard>
+### Variant Selection
 
-  {/* Small */}
-  <AtomicCard padding="sm">
-    <Text>Small padding</Text>
-  </AtomicCard>
+1. **Elevated**: Default, for most cards with depth
+2. **Outlined**: For less emphasis, grouping content
+3. **Filled**: For highest emphasis or contrasting backgrounds
 
-  {/* Medium (Varsayılan) */}
-  <AtomicCard padding="md">
-    <Text>Medium padding</Text>
-  </AtomicCard>
+### Padding Guidelines
 
-  {/* Large */}
-  <AtomicCard padding="lg">
-    <Text>Large padding</Text>
-  </AtomicCard>
-</View>
-```
+1. **None**: When content has its own padding or is full-width
+2. **Small (sm)**: For dense content or compact cards
+3. **Medium (md)**: Default for most cards
+4. **Large (lg)**: For spacious cards with minimal content
+
+### Pressable Cards
+
+1. **MUST** provide `onPress` callback
+2. **SHOULD** have visual feedback
+3. **MUST** announce interactivity to screen readers
+4. **SHOULD** have clear affordance (icon, chevron, etc.)
+
+## Forbidden
 
-## Pressable Card
+❌ **NEVER** do these:
 
 ```tsx
+// ❌ Empty card
+<AtomicCard /> {/* ❌ No content */}
+
+// ❌ Wrong variant for emphasis
+<AtomicCard variant="elevated"> {/* ❌ Too much emphasis */}
+  <AtomicText type="bodySmall">Small hint</AtomicText>
+</AtomicCard>
+
+// ❌ Pressable without callback
 <AtomicCard
-  onPress={() => console.log('Kart tıklandı!')}
-  padding="md"
+  onPress {/* ❌ Missing handler */}
 >
-  <Text>Tıklanabilir Kart</Text>
-  <Text>Tıklamayı dene</Text>
+  <AtomicText>Click me</AtomicText>
 </AtomicCard>
-```
-
-## Örnek Kullanımlar
 
-### Profil Kartı
+// ❌ Deep nesting
+<AtomicCard>
+  <AtomicCard>
+    <AtomicCard> {/* ❌ Too nested */}
+      <Content />
+    </AtomicCard>
+  </AtomicCard>
+</AtomicCard>
 
-```tsx
-<AtomicCard variant="elevated" padding="md">
-  <View style={{ alignItems: 'center' }}>
-    <Text style={{ fontSize: 20, fontWeight: 'bold' }}>Ahmet Yılmaz</Text>
-    <Text style={{ color: 'gray' }}>Frontend Developer</Text>
+// ❌ Inconsistent padding
+<AtomicCard padding="none">
+  <View style={{ padding: 20 }}> {/* ❌ Manual padding */}
+    <Content />
   </View>
 </AtomicCard>
-```
 
-### Ürün Kartı
+// ❌ Card for simple border
+<AtomicCard variant="outlined">
+  <Content />
+</AtomicCard>
+// ❌ Should use View with borderStyle instead
 
-```tsx
-<AtomicCard
-  variant="outlined"
-  padding="md"
-  onPress={() => navigate('ProductDetail')}
->
-  <Text style={{ fontSize: 16, fontWeight: '600' }}>Ürün Adı</Text>
-  <Text style={{ marginTop: 8 }}>Ürün açıklaması</Text>
-  <Text style={{ marginTop: 16, fontSize: 18, fontWeight: 'bold' }}>$99.99</Text>
+// ❌ Pressable card without accessibility context
+<AtomicCard onPress={handleAction}>
+  <AtomicText>Click</AtomicText>
 </AtomicCard>
+// ❌ No accessibilityLabel or hint
 ```
 
-### Bilgi Kartı
+## Best Practices
+
+### Variant Selection
 
+✅ **DO**:
 ```tsx
+// ✅ Default elevated card
+<AtomicCard variant="elevated">
+  <ProductDetails />
+</AtomicCard>
+
+// ✅ List item with outline
+<FlatList
+  data={items}
+  renderItem={({ item }) => (
+    <AtomicCard variant="outlined" padding="sm">
+      <ListItemContent item={item} />
+    </AtomicCard>
+  )}
+/>
+
+// ✅ Highlighted section with filled
 <AtomicCard variant="filled" padding="lg">
-  <Text style={{ fontSize: 18, fontWeight: 'bold', marginBottom: 8 }}>
-    Önemli Bilgi
-  </Text>
-  <Text style={{ lineHeight: 22 }}>
-    Bu kart önemli bilgileri içermektedir.
-    Lütfen dikkatlice okuyunuz.
-  </Text>
+  <FeaturedContent />
 </AtomicCard>
 ```
 
-### Liste Elemanı
-
+❌ **DON'T**:
 ```tsx
-{items.map((item) => (
-  <AtomicCard
-    key={item.id}
-    variant="outlined"
-    padding="sm"
-    onPress={() => handleItemPress(item)}
-    style={{ marginBottom: 12 }}
-  >
-    <View style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
-      <Text>{item.title}</Text>
-      <Text>{item.date}</Text>
-    </View>
-  </AtomicCard>
-))}
-```
+// ❌ Over-emphasizing minor content
+<AtomicCard variant="elevated">
+  <AtomicText type="bodySmall">Tip</AtomicText>
+</AtomicCard>
 
-## Props
+// ❌ Under-emphasizing important content
+<AtomicCard variant="outlined">
+  <AtomicText type="headlineLarge">Critical Alert</AtomicText>
+</AtomicCard>
+```
 
-### AtomicCardProps
+### Padding Usage
 
-| Prop | Tip | Varsayılan | Açıklama |
-|------|-----|------------|----------|
-| `children` | `ReactNode` | - **(Zorunlu)** | Kart içeriği |
-| `variant` | `AtomicCardVariant` | `'elevated'` | Kart görünüm stili |
-| `padding` | `AtomicCardPadding` | `'md'` | İç boşluk miktarı |
-| `onPress` | `(event: GestureResponderEvent) => void` | - | Tıklama olayı |
-| `disabled` | `boolean` | `false` | Devre dışı |
-| `style` | `StyleProp<ViewStyle>` | - | Özel stil |
-| `testID` | `string` | - | Test ID'si |
+✅ **DO**:
+```tsx
+// ✅ Dense content
+<AtomicCard variant="outlined" padding="sm">
+  <DenseListItems />
+</AtomicCard>
 
-### AtomicCardVariant
+// ✅ Normal content
+<AtomicCard padding="md">
+  <CardContent />
+</AtomicCard>
 
-```typescript
-type AtomicCardVariant =
-  | 'elevated'  // Gölge efekti (varsayılan)
-  | 'outlined'  // Çerçeve efekti
-  | 'filled';   // Dolgu efekti
+// ✅ Minimal content
+<AtomicCard padding="lg">
+  <AtomicText align="center">Empty State</AtomicText>
+</AtomicCard>
 ```
 
-### AtomicCardPadding
+❌ **DON'T**:
+```tsx
+// ❌ No padding with unpadded content
+<AtomicCard padding="none">
+  <AtomicText>No breathing room</AtomicText>
+</AtomicCard>
 
-```typescript
-type AtomicCardPadding =
-  | 'none'  // İç boşluk yok
-  | 'sm'    // Küçük iç boşluk
-  | 'md'    // Orta iç boşluk (varsayılan)
-  | 'lg';   // Büyük iç boşluk
+// ❌ Too much padding
+<AtomicCard padding="lg">
+  <DenseContent />
+</AtomicCard>
 ```
 
-## Stil Özelleştirme
+### Pressable Cards
 
+✅ **DO**:
 ```tsx
+// ✅ Interactive card
 <AtomicCard
-  variant="elevated"
+  onPress={() => navigate('Detail', { id })}
   padding="md"
-  style={{
-    backgroundColor: '#f8f9fa',
-    borderRadius: 16,
-    borderWidth: 2,
-    borderColor: '#e9ecef',
-    shadowColor: '#000',
-    shadowOffset: { width: 0, height: 2 },
-    shadowOpacity: 0.1,
-    shadowRadius: 4,
-    elevation: 3,
-  }}
 >
-  <Text>Özel Stilli Kart</Text>
+  <View style={{ flexDirection: 'row' }}>
+    <View style={{ flex: 1 }}>
+      <AtomicText fontWeight="600">Title</AtomicText>
+      <AtomicText type="bodySmall" color="textSecondary">
+        Description
+      </AtomicText>
+    </View>
+    <AtomicIcon name="chevron-forward" />
+  </View>
 </AtomicCard>
 ```
 
-## Best Practices
-
-### 1. Variant Seçimi
-
+❌ **DON'T**:
 ```tsx
-// Ana içerik için elevated
-<AtomicCard variant="elevated">
-  <ImportantContent />
+// ❌ Pressable without clear affordance
+<AtomicCard onPress={handleAction}>
+  <AtomicText>Click me somehow</AtomicText>
 </AtomicCard>
 
-// Liste elemanları için outlined
-<FlatList
-  data={items}
-  renderItem={({ item }) => (
-    <AtomicCard variant="outlined" padding="sm">
-      {item.content}
-    </AtomicCard>
-  )}
-/>
-
-// Arka plan için filled
-<AtomicCard variant="filled">
-  <BackgroundContent />
+// ❌ Missing accessibility
+<AtomicCard onPress={handleAction}>
+  <Content />
 </AtomicCard>
 ```
 
-### 2. Padding Kullanımı
+### Content Organization
 
+✅ **DO**:
 ```tsx
-// Yoğun içerik için az padding
-<AtomicCard padding="sm">
-  <DenseContent />
+// ✅ Structured card content
+<AtomicCard padding="md">
+  <View style={{ marginBottom: 12 }}>
+    <AtomicText type="titleMedium">Title</AtomicText>
+  </View>
+  <View style={{ marginBottom: 12 }}>
+    <AtomicText type="bodyMedium">Description</AtomicText>
+  </View>
+  <View>
+    <AtomicText type="bodySmall" color="textSecondary">
+      Metadata
+    </AtomicText>
+  </View>
 </AtomicCard>
+```
 
-// Boş içerik için fazla padding
-<AtomicCard padding="lg">
-  <SparseContent />
+❌ **DON'T**:
+```tsx
+// ❌ Unstructured content
+<AtomicCard>
+  <AtomicText>Title</AtomicText>
+  <AtomicText>Description</AtomicText>
+  <AtomicText>More</AtomicText>
+  <AtomicText>Even more</AtomicText>
+  {/* No spacing or hierarchy */}
 </AtomicCard>
 ```
 
-### 3. Pressable Kullanım
+## AI Coding Guidelines
+
+### For AI Agents
+
+When generating AtomicCard components, follow these rules:
+
+1. **Always import from correct path**:
+   ```typescript
+   import { AtomicCard } from 'react-native-design-system/src/atoms/AtomicCard';
+   ```
+
+2. **Always choose appropriate variant**:
+   ```tsx
+   // ✅ Good - variant matches emphasis
+   <AtomicCard variant="elevated">
+     <ImportantContent />
+   </AtomicCard>
+   <AtomicCard variant="outlined">
+     <SecondaryContent />
+   </AtomicCard>
+
+   // ❌ Bad - wrong variant
+   <AtomicCard variant="elevated">
+     <MinorHint />
+   </AtomicCard>
+   ```
+
+3. **Always use padding appropriately**:
+   ```tsx
+   // ✅ Good - padding matches content density
+   <AtomicCard padding="sm">
+     <DenseContent />
+   </AtomicCard>
+   <AtomicCard padding="lg">
+     <MinimalContent />
+   </AtomicCard>
+
+   // ❌ Bad - wrong padding
+   <AtomicCard padding="none">
+     <ContentWithoutSpacing />
+   </AtomicCard>
+   ```
+
+4. **Always handle pressable cards properly**:
+   ```tsx
+   // ✅ Good - pressable with affordance
+   <AtomicCard
+     onPress={() => navigate('Detail')}
+     accessibilityLabel="View details"
+     accessibilityRole="button"
+   >
+     <View style={{ flexDirection: 'row', alignItems: 'center' }}>
+       <View style={{ flex: 1 }}>
+         <AtomicText fontWeight="600">Title</AtomicText>
+       </View>
+       <AtomicIcon name="chevron-forward" />
+     </View>
+   </AtomicCard>
+
+   // ❌ Bad - pressable without affordance
+   <AtomicCard onPress={handleAction}>
+     <AtomicText>Click me</AtomicText>
+   </AtomicCard>
+   ```
+
+5. **Always structure card content**:
+   ```tsx
+   // ✅ Good - clear structure
+   <AtomicCard padding="md">
+     <View style={{ marginBottom: 12 }}>
+       <AtomicText type="titleMedium">Title</AtomicText>
+     </View>
+     <View>
+       <AtomicText type="bodyMedium">Content</AtomicText>
+     </View>
+   </AtomicCard>
+
+   // ❌ Bad - no structure
+   <AtomicCard>
+     <AtomicText>Title</AtomicText>
+     <AtomicText>Content</AtomicText>
+   </AtomicCard>
+   ```
+
+### Common Patterns
+
+#### Basic Card
+```tsx
+<AtomicCard padding="md">
+  <AtomicText>Card content</AtomicText>
+</AtomicCard>
+```
 
+#### Clickable Card
 ```tsx
-// Tıklanabilir öğeler
 <AtomicCard
-  onPress={handlePress}
-  style={{ marginBottom: 8 }}
+  onPress={() => navigate('Detail')}
+  padding="md"
+  accessibilityLabel="View details"
 >
-  <CardHeader />
-  <CardContent />
-  <CardFooter />
+  <Content />
 </AtomicCard>
 ```
 
-## Erişilebilirlik
-
-AtomicCard, tam erişilebilirlik desteği sunar:
+#### List Item Card
+```tsx
+<FlatList
+  data={items}
+  renderItem={({ item }) => (
+    <AtomicCard
+      key={item.id}
+      variant="outlined"
+      padding="sm"
+      onPress={() => handleItemPress(item)}
+      style={{ marginBottom: 12 }}
+    >
+      <ListItemContent item={item} />
+    </AtomicCard>
+  )}
+/>
+```
 
-- ✅ Touch uygun boyut
-- ✅ Screen reader desteği
-- ✅ Disabled state anonsu
-- ✅ Test ID desteği
+#### Product Card
+```tsx
+<AtomicCard variant="elevated" padding="md">
+  <AtomicText type="titleMedium" fontWeight="600">
+    {product.name}
+  </AtomicText>
+  <AtomicText type="bodyMedium" color="textSecondary" marginTop="sm">
+    {product.description}
+  </AtomicText>
+  <AtomicText type="titleLarge" color="primary" marginTop="md">
+    ${product.price}
+  </AtomicText>
+</AtomicCard>
+```
 
-## Performans İpuçları
+## Props Reference
 
-1. **FlatList ile Kullanım**: Listelerde `key` prop'unu kullanın
-2. **Inline Styles**: Mümkün olduğunca theme kullanın
-3. **Re-renders**: Kart içeriğini `React.memo` ile sarın
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | Yes | - | Card content |
+| `variant` | `'elevated' \| 'outlined' \| 'filled'` | No | `'elevated'` | Card visual style |
+| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | No | `'md'` | Internal padding |
+| `onPress` | `(event: GestureResponderEvent) => void` | No | - | Press callback |
+| `disabled` | `boolean` | No | `false` | Disable press |
+| `style` | `ViewStyle` | No | - | Custom style |
+| `testID` | `string` | No | - | Test identifier |
 
-## İlgili Bileşenler
+### AtomicCardVariant
 
-- [`MediaCard`](../../molecules/media-card/README.md) - Medya kartı
-- [`GlowingCard`](../../molecules/GlowingCard/README.md) - Parlak kart
-- [`FormField`](../../molecules/FormField/README.md) - Form alanı
+```typescript
+type AtomicCardVariant =
+  | 'elevated'  // Shadow effect (default)
+  | 'outlined'  // Border effect
+  | 'filled';   // Background fill effect
+```
 
-## Örnek Proje
+### AtomicCardPadding
 
-```tsx
-import React from 'react';
-import { View, ScrollView, Text, Image } from 'react-native';
-import { AtomicCard } from 'react-native-design-system';
-
-export const CardGallery = () => {
-  return (
-    <ScrollView style={{ padding: 16 }}>
-      {/* Basit Kart */}
-      <AtomicCard variant="elevated" padding="md" style={{ marginBottom: 16 }}>
-        <Text style={{ fontSize: 18, fontWeight: 'bold' }}>
-          Basit Kart
-        </Text>
-        <Text style={{ marginTop: 8 }}>
-          Bu basit bir kart örneğidir.
-        </Text>
-      </AtomicCard>
-
-      {/* Tıklanabilir Kart */}
-      <AtomicCard
-        variant="outlined"
-        padding="md"
-        onPress={() => console.log('Tıklandı!')}
-        style={{ marginBottom: 16 }}
-      >
-        <Text style={{ fontSize: 18, fontWeight: 'bold' }}>
-          Tıklanabilir Kart
-        </Text>
-        <Text style={{ marginTop: 8, color: '#6366f1' }}>
-          Tıkla ve gör
-        </Text>
-      </AtomicCard>
-
-      {/* Filled Kart */}
-      <AtomicCard variant="filled" padding="lg" style={{ marginBottom: 16 }}>
-        <Text style={{ fontSize: 18, fontWeight: 'bold' }}>
-          Filled Kart
-        </Text>
-        <Text style={{ marginTop: 8, lineHeight: 22 }}>
-          Bu kartın dolgu efekti vardır.
-        </Text>
-      </AtomicCard>
-    </ScrollView>
-  );
-};
+```typescript
+type AtomicCardPadding =
+  | 'none'  // No padding
+  | 'sm'    // Small padding
+  | 'md'    // Medium padding (default)
+  | 'lg';   // Large padding
 ```
 
-## Lisans
+## Accessibility
+
+- ✅ Touch target size maintained (min 44x44pt)
+- ✅ Screen reader support for pressable cards
+- ✅ Disabled state announced
+- ✅ Test ID support for testing
+
+## Performance Tips
+
+1. **FlatList optimization**: Provide `key` prop for list items
+2. **Avoid inline styles**: Use theme tokens or StyleSheet
+3. **Memoization**: Memo card content if complex
+4. **Limit nesting**: Don't nest cards more than 2 levels
+
+## Related Components
+
+- [`MediaCard`](../molecules/media-card) - Media card with image
+- [`GlowingCard`](../molecules/GlowingCard) - Glowing effect card
+- [`FormField`](../molecules/FormField) - Form field component
+
+## License
 
 MIT