klz-cables.com/components/ui/README.md

# UI Components

A comprehensive design system of reusable UI components for the KLZ Cables Next.js application. Built with TypeScript, Tailwind CSS, and accessibility best practices.

## Overview

This component library provides building blocks for creating consistent, responsive, and accessible user interfaces. All components are fully typed with TypeScript and follow modern web standards.

## Components

### 1. Button Component

A versatile button component with multiple variants, sizes, and states.

**Features:**
- Multiple variants: `primary`, `secondary`, `outline`, `ghost`
- Three sizes: `sm`, `md`, `lg`
- Icon support with left/right positioning
- Loading state with spinner
- Full width option
- Proper accessibility attributes

**Usage:**
```tsx
import { Button } from '@/components/ui';

// Basic usage
<Button variant="primary" size="md">Click me</Button>

// With icon
<Button 
  variant="primary" 
  icon={<ArrowRightIcon />} 
  iconPosition="right"
>
  Next
</Button>

// Loading state
<Button variant="primary" loading>Processing...</Button>

// Disabled
<Button variant="primary" disabled>Not available</Button>

// Full width
<Button variant="primary" fullWidth>Submit</Button>
```

### 2. Card Component

Flexible container component with optional header, body, footer, and image sections.

**Features:**
- Three variants: `elevated`, `flat`, `bordered`
- Optional padding: `none`, `sm`, `md`, `lg`, `xl`
- Hover effects
- Image support (top or background)
- Composable sub-components

**Usage:**
```tsx
import { Card, CardHeader, CardBody, CardFooter, CardImage } from '@/components/ui';

// Basic card
<Card variant="elevated" padding="md">
  <CardHeader title="Title" subtitle="Subtitle" />
  <CardBody>
    <p>Card content goes here</p>
  </CardBody>
  <CardFooter>
    <Button variant="primary">Action</Button>
  </CardFooter>
</Card>

// Card with image
<Card variant="flat" padding="none">
  <CardImage 
    src="/image.jpg" 
    alt="Description" 
    height="md"
  />
  <div className="p-4">
    <CardHeader title="Image Card" />
  </div>
</Card>

// Hoverable card
<Card variant="elevated" hoverable>
  {/* content */}
</Card>
```

### 3. Container Component

Responsive wrapper for centering content with configurable max-width and padding.

**Features:**
- Max-width options: `xs` to `6xl`, `full`
- Padding options: `none`, `sm`, `md`, `lg`, `xl`, `2xl`
- Centering option
- Fluid mode (full width)

**Usage:**
```tsx
import { Container } from '@/components/ui';

// Standard container
<Container maxWidth="6xl" padding="lg">
  <YourContent />
</Container>

// Medium container
<Container maxWidth="md" padding="md">
  <YourContent />
</Container>

// Fluid (full width)
<Container fluid>
  <YourContent />
</Container>

// Without centering
<Container maxWidth="lg" centered={false}>
  <YourContent />
</Container>
```

### 4. Grid Component

Responsive grid system with configurable columns and gaps.

**Features:**
- 1-12 column system
- Responsive breakpoints: `colsSm`, `colsMd`, `colsLg`, `colsXl`
- Gap spacing: `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`
- Grid item span control
- Alignment options

**Usage:**
```tsx
import { Grid, GridItem } from '@/components/ui';

// Basic grid
<Grid cols={3} gap="md">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Grid>

// Responsive grid
<Grid cols={1} colsMd={2} colsLg={4} gap="lg">
  {/* items */}
</Grid>

// Grid with spans
<Grid cols={3} gap="md">
  <GridItem colSpan={2}>Spans 2 columns</GridItem>
  <GridItem>1 column</GridItem>
</GridItem>

// Grid with alignment
<Grid cols={2} gap="md" alignItems="center" justifyItems="center">
  {/* items */}
</Grid>
```

### 5. Badge Component

Small status or label component with multiple variants.

**Features:**
- Color variants: `primary`, `secondary`, `success`, `warning`, `error`, `info`, `neutral`
- Sizes: `sm`, `md`, `lg`
- Icon support with positioning
- Rounded or squared
- Badge group for multiple badges

**Usage:**
```tsx
import { Badge, BadgeGroup } from '@/components/ui';

// Basic badge
<Badge variant="success">Active</Badge>

// With icon
<Badge variant="primary" icon={<StarIcon />}>Featured</Badge>

// Different sizes
<Badge variant="warning" size="sm">Small</Badge>
<Badge variant="warning" size="md">Medium</Badge>
<Badge variant="warning" size="lg">Large</Badge>

// Badge group
<BadgeGroup gap="sm">
  <Badge variant="primary">React</Badge>
  <Badge variant="secondary">TypeScript</Badge>
  <Badge variant="info">Tailwind</Badge>
</BadgeGroup>

// Rounded
<Badge variant="primary" rounded={true}>Rounded</Badge>
```

### 6. Loading Component

Loading indicators including spinners, buttons, and skeletons.

**Features:**
- Spinner sizes: `sm`, `md`, `lg`, `xl`
- Spinner variants: `primary`, `secondary`, `neutral`, `contrast`
- Optional text
- Overlay mode with fullscreen option
- Loading button
- Skeleton loaders

**Usage:**
```tsx
import { Loading, LoadingButton, LoadingSkeleton } from '@/components/ui';

// Basic spinner
<Loading size="md" />

// With text
<Loading size="md" text="Loading data..." />

// Overlay (blocks UI)
<Loading size="lg" overlay text="Please wait..." />

// Fullscreen overlay
<Loading size="xl" overlay fullscreen text="Loading..." />

// Loading button
<LoadingButton size="md" text="Processing..." />

// Skeleton loaders
<LoadingSkeleton width="100%" height="1rem" />
<LoadingSkeleton width="80%" height="1rem" rounded />
```

## TypeScript Support

All components are fully typed with TypeScript. Props are exported for external use:

```tsx
import type { 
  ButtonProps, 
  CardProps, 
  ContainerProps,
  GridProps,
  BadgeProps,
  LoadingProps 
} from '@/components/ui';
```

## Accessibility

All components include proper accessibility attributes:
- ARIA labels where needed
- Keyboard navigation support
- Focus management
- Screen reader friendly
- Color contrast compliance

## Responsive Design

Components are built with mobile-first responsive design:
- Tailwind responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`)
- Flexible layouts
- Touch-friendly sizes
- Adaptive spacing

## Customization

All components support the `className` prop for custom styling:

```tsx
<Button 
  variant="primary" 
  className="custom-class hover:scale-105"
>
  Custom Button
</Button>
```

## Best Practices

1. **Always use the index export:**
   ```tsx
   import { Button, Card } from '@/components/ui';
   ```

2. **Type your props:**
   ```tsx
   interface MyComponentProps {
     title: string;
     variant?: ButtonVariant;
   }
   ```

3. **Use semantic HTML:**
   - Buttons for actions
   - Links for navigation
   - Proper heading hierarchy

4. **Test with keyboard:**
   - Tab through all interactive elements
   - Enter/Space activates buttons
   - Escape closes modals

5. **Test with screen readers:**
   - Use VoiceOver (macOS) or NVDA (Windows)
   - Verify ARIA labels are descriptive

## Performance Tips

1. **Lazy load heavy components:**
   ```tsx
   const HeavyComponent = dynamic(() => import('@/components/Heavy'), {
     loading: () => <Loading size="md" />
   });
   ```

2. **Memoize expensive computations:**
   ```tsx
   const memoizedValue = useMemo(() => computeExpensiveValue(), [deps]);
   ```

3. **Use proper image optimization:**
   ```tsx
   <CardImage 
     src="/optimized-image.jpg" 
     alt="Description"
     // Next.js Image component recommended for production
   />
   ```

## Browser Support

- Chrome/Edge: Latest 2 versions
- Firefox: Latest 2 versions
- Safari: Latest 2 versions
- Mobile browsers: iOS Safari, Chrome Mobile

## Future Enhancements

- [ ] Modal component
- [ ] Dropdown component
- [ ] Tabs component
- [ ] Accordion component
- [ ] Tooltip component
- [ ] Toast/Notification component
- [ ] Form input components
- [ ] Table component

## Contributing

When adding new components:
1. Follow the existing component structure
2. Use TypeScript interfaces
3. Include proper accessibility attributes
4. Add to the index export
5. Update this documentation
6. Test across browsers and devices

## License

Internal use only - KLZ Cables