# KLZ Cables Design System Foundation

## Overview
This document outlines the comprehensive design system foundation created for the KLZ Cables website migration from WordPress to Next.js with Tailwind CSS. The design system establishes a consistent, modern foundation that matches the original WordPress site while using contemporary development patterns.

## Files Created/Modified

### 1. `tailwind.config.js` (Updated)
**Purpose**: Extended Tailwind configuration with brand-specific design tokens.

**Key Additions**:
- **Brand Colors**: Primary (#0056b3), Secondary (#003d82), Accent (#e6f0ff), Neutral (#f8f9fa)
- **Text Colors**: Primary (#1a1a1a), Secondary (#6c757d), Light (#adb5bd)
- **Typography Scale**: Complete font size system from xs (12px) to 6xl (60px)
- **Font Weights**: Regular (400) to Extrabold (800)
- **Spacing System**: Consistent scale from xs (4px) to 4xl (96px)
- **Border Radius**: Sm (4px) to 2xl (24px)
- **Shadows**: Complete elevation system
- **Container**: Responsive breakpoints with padding

### 2. `styles/design-tokens.scss` (New)
**Purpose**: CSS custom properties for design tokens that can be used throughout the application.

**Features**:
- **CSS Variables**: 50+ custom properties for colors, typography, spacing, shadows
- **Dark Mode Support**: Media query for future dark mode implementation
- **Base Element Styles**: Fundamental styles for HTML elements using tokens
- **Utility Classes**: Common utility classes for quick styling

**Color Palette**:
```scss
--color-primary: #0056b3;        /* Main brand blue */
--color-primary-dark: #003d82;   /* Darker blue for hover states */
--color-primary-light: #e6f0ff;  /* Light blue for backgrounds */
--color-secondary: #003d82;      /* Secondary blue */
--color-accent: #e6f0ff;         /* Accent light blue */
--color-neutral: #f8f9fa;        /* Neutral gray background */
--color-text-primary: #1a1a1a;   /* Dark text */
--color-text-secondary: #6c757d; /* Medium gray text */
```

### 3. `styles/base.scss` (New)
**Purpose**: Establishes typography scale, spacing system, and comprehensive base element styles.

**Components**:

#### Typography Scale
- **Display Headings**: `.display-1` (2.5-4rem), `.display-2` (2-3rem)
- **Section Headings**: `.heading-1` to `.heading-4` (4xl to xl)
- **Body Text**: `.text-body`, `.text-body-large`, `.text-body-small`, `.text-body-tiny`
- **Utilities**: `.text-muted`, `.text-light`, `.text-inverse`, alignment classes

#### Spacing System
- **Margin**: `.m-xs` to `.m-3xl`, `.mt-*`, `.mb-*`, `.ml-*`, `.mr-*`
- **Padding**: `.p-xs` to `.p-3xl`, `.pt-*`, `.pb-*`, `.pl-*`, `.pr-*`

#### Base Elements
- **HTML/Body**: Font smoothing, line height, colors
- **Headings**: All h1-h6 with proper sizing and weights
- **Links**: Hover states, transitions
- **Lists**: Ordered/unordered with proper spacing
- **Forms**: Inputs, textareas, selects with focus states
- **Tables**: Clean, responsive tables
- **Code**: Monospace with background
- **Blockquotes**: Styled with left border

#### Layout Components
- **Container**: Responsive max-width with padding
- **Section**: Padding for content sections
- **Grid**: `.grid-2`, `.grid-3`, `.grid-4` with auto-fit
- **Flexbox**: `.flex`, `.flex-col`, alignment, justification, gap utilities

#### Components
- **Card**: Shadow, hover, border radius
- **Buttons**: `.btn-primary`, `.btn-secondary`, `.btn-outline`, `.btn-ghost` with sizes
- **Badge**: Inline badges with variants
- **Alert**: Info, success, warning, danger variants

#### Responsive Utilities
- **Mobile-first**: All components responsive by default
- **Breakpoints**: Specific overrides at 768px
- **Typography**: Scaled down for mobile

#### Accessibility
- **Focus Visible**: Keyboard navigation styles
- **Reduced Motion**: Respects user preferences
- **Print Styles**: Clean print output

### 4. `app/globals.scss` (Updated)
**Purpose**: Main global stylesheet that imports the design system and provides component-specific styles.

**Structure**:
1. **Tailwind Directives**: Base, components, utilities
2. **Design System Imports**: Tokens and base styles
3. **Component Styles**: Navigation, forms, products, blog, content
4. **Utilities**: Common utility classes
5. **Responsive**: Mobile-specific overrides
6. **Print**: Print media queries

**Key Components**:
- **Navigation**: Sticky header, responsive menu, active states
- **Contact Form**: Form groups, inputs, validation states
- **Cookie Consent**: Fixed bottom bar with buttons
- **Product Grid**: Cards with images, titles, prices
- **Blog Cards**: Article previews with metadata
- **Content**: Rich content styling with proper hierarchy
- **Hero Section**: Ready for future hero components

## Design Principles

### 1. Consistency
- All colors, spacing, and typography use systematic scales
- Components share common patterns and behaviors
- Transitions and animations are standardized

### 2. Maintainability
- CSS variables for easy theming
- Modular file structure
- Clear naming conventions
- Comprehensive documentation

### 3. Accessibility
- Proper color contrast ratios
- Keyboard navigation support
- Screen reader friendly
- Reduced motion support

### 4. Responsiveness
- Mobile-first approach
- Fluid typography with clamp()
- Flexible grid systems
- Touch-friendly targets

### 5. Performance
- Minimal CSS output
- Efficient selectors
- No unused styles
- Optimized for production

## Usage Examples

### Using Tailwind Classes
```tsx
<div className="bg-primary text-white p-lg rounded-lg shadow-md">
  <h2 className="heading-2 mb-md">Title</h2>
  <p className="text-body">Content here</p>
  <button className="btn btn-primary">Click me</button>
</div>
```

### Using CSS Variables
```css
.custom-component {
  background: var(--color-primary-light);
  padding: var(--spacing-lg);
  border-radius: var(--radius-md);
  color: var(--color-text-primary);
}
```

### Using Base Classes
```tsx
<article className="card">
  <h3 className="heading-3">Article Title</h3>
  <p className="text-body">Article content with proper spacing.</p>
</article>
```

## Next Steps

With this foundation in place, you can now:

1. **Extract Components**: Use the design system to create reusable React components
2. **Build Pages**: Create consistent page layouts using the grid and spacing system
3. **Add Features**: Implement new functionality with consistent styling
4. **Theme**: Easily adjust colors or add dark mode using CSS variables
5. **Scale**: Add new components that follow the established patterns

## Migration Benefits

✅ **Modern Stack**: Tailwind CSS with Next.js
✅ **Consistent Design**: Systematic approach to styling
✅ **Type Safety**: TypeScript-ready
✅ **Performance**: Optimized CSS output
✅ **Maintainable**: Clear structure and documentation
✅ **Accessible**: Built-in accessibility features
✅ **Responsive**: Mobile-first design
✅ **Future-proof**: Easy to extend and modify

This design system foundation provides everything needed to rebuild the KLZ Cables website with modern, maintainable, and beautiful styling that matches the original brand while leveraging the power of Tailwind CSS and Next.js.