migration wip
This commit is contained in:
367
components/ui/README.md
Normal file
367
components/ui/README.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user