# Awesome Mall - Styling & Design System

**Project:** Awesome Mall E-commerce Platform  
**Last Updated:** January 13, 2026  
**Design Philosophy:** Modern, Clean, Premium E-commerce Experience

---

## 📋 Table of Contents
1. [Design System Overview](#design-system-overview)
2. [Color Palette](#color-palette)
3. [Typography](#typography)
4. [CSS Architecture](#css-architecture)
5. [Component Structure](#component-structure)
6. [Layout System](#layout-system)
7. [Responsive Breakpoints](#responsive-breakpoints)
8. [Animation & Transitions](#animation--transitions)
9. [CSS File Organization](#css-file-organization)
10. [Best Practices](#best-practices)

---

## 1. Design System Overview

### Design Goals:
- **Modern & Premium**: State-of-the-art e-commerce aesthetics
- **User-Centric**: Intuitive navigation and interactions
- **Brand Consistency**: Cohesive visual language throughout
- **Performance**: Optimized for fast loading and smooth animations
- **Accessibility**: WCAG compliant color contrasts and interactions

### Core Principles:
1. **Flat Design**: Minimal shadows, clean borders
2. **Vibrant Colors**: Orange/red brand identity
3. **Micro-animations**: Subtle motion for engagement
4. **Mobile-First**: Responsive from smallest to largest screens
5. **Component-Based**: Reusable UI elements

---

## 2. Color Palette

### Primary Colors:
```css
:root {
  --am-primary: #E8663D;           /* Main brand orange */
  --am-primary-hover: #d25532;     /* Hover state (darker) */
  --am-corporate-blue: #003A70;    /* Secondary brand color */
}
```

### Color Usage:

#### Orange (#E8663D):
- **Purpose**: Primary brand color, calls-to-action
- **Used for**:
  - Primary buttons
  - Links and highlights
  - Active states
  - Price tags
  - Brand elements
  - Icons in bottom navigation

#### Corporate Blue (#003A70):
- **Purpose**: Secondary actions, professional elements
- **Used for**:
  - Add-to-cart buttons
  - Alternative buttons
  - Headers in admin sections
  - Trust signals

### Neutral Colors:
```css
/* Backgrounds */
--bg-page: #f8f9fa;              /* Page background */
--bg-white: #fff;                /* Card/section backgrounds */
--bg-footer: #222;               /* Dark footer */

/* Text */
--text-primary: #1a1a1a;         /* Headings, important text */
--text-secondary: #666;          /* Body text */
--text-muted: #999;              /* Helper text, placeholders */

/* Borders */
--border-light: #eee;            /* Light borders */
--border-medium: #e0e0e0;        /* Medium borders */
--border-dark: #ccc;             /* Dark borders */
```

### Semantic Colors:
```css
/* Success */
--success: #00C851;
--success-light: #e8f5e9;

/* Error */
--error: #d32f2f;
--error-light: #fee;

/* Warning */
--warning: #ffc107;
--warning-light: #fff3cd;

/* Info */
--info: #2196f3;
--info-light: #e3f2fd;
```

### Color Accessibility:
- Primary orange (#E8663D) on white: **4.5:1 contrast** ✅
- Corporate blue (#003A70) on white: **11.3:1 contrast** ✅
- Text colors meet WCAG AA standard

---

## 3. Typography

### Font Families:
```css
/* Primary Font */
font-family: 'Inter', sans-serif;

/* Fallback Stack */
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 
             'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 
             sans-serif;
```

### Font Weights:
```css
--font-regular: 400;
--font-medium: 500;
--font-semibold: 600;
--font-bold: 700;
```

### Type Scale:
```css
/* Headings */
h1, .h1 { font-size: 32px; font-weight: 700; line-height: 1.2; }
h2, .h2 { font-size: 28px; font-weight: 700; line-height: 1.3; }
h3, .h3 { font-size: 24px; font-weight: 600; line-height: 1.3; }
h4, .h4 { font-size: 20px; font-weight: 600; line-height: 1.4; }
h5, .h5 { font-size: 18px; font-weight: 600; line-height: 1.4; }
h6, .h6 { font-size: 16px; font-weight: 600; line-height: 1.4; }

/* Body Text */
body { font-size: 15px; line-height: 1.6; }
small { font-size: 13px; }

/* UI Elements */
.btn { font-size: 15px; font-weight: 600; }
input { font-size: 14px; }
label { font-size: 14px; font-weight: 500; }
```

### Mobile Typography Adjustments:
```css
@media (max-width: 767px) {
  h1 { font-size: 24px; }
  h2 { font-size: 20px; }
  h3 { font-size: 18px; }
  body { font-size: 14px; }
}
```

---

## 4. CSS Architecture

### File Structure:
```
assets/css/
├── components.css         # Component-specific styles
├── awesome-layout.css     # Page layouts and sections
├── awesome-extras.css     # Additional components
├── responsive.css         # Mobile responsiveness
├── variables.css          # CSS custom properties
└── shop-category.css      # Category page styles
```

### Loading Order (in head.php):
1. Bootstrap 5.3.0 (CDN)
2. Font Awesome 6.4.0
3. Custom variables
4. Components
5. Layout
6. Extras
7. Responsive (last)

### CSS Methodology:
- **BEM-inspired** naming for components
- **Utility classes** where appropriate
- **Component isolation** to prevent conflicts
- **Mobile-first** media queries

---

## 5. Component Structure

### Buttons

#### Primary Button:
```css
.btn-primary {
  background: var(--am-primary);
  color: #fff;
  border: none;
  border-radius: 8px;
  padding: 12px 24px;
  font-weight: 600;
  transition: all 0.3s;
}

.btn-primary:hover {
  background: var(--am-primary-hover);
  transform: translateY(-1px);
  box-shadow: 0 4px 12px rgba(232, 102, 61, 0.3);
}
```

#### Add-to-Cart Button:
```css
.btn-add-cart {
  display: block;
  background: var(--am-corporate-blue);
  color: #fff;
  text-align: center;
  padding: 8px 10px;
  font-size: 12px;
  font-weight: 600;
  border-radius: 4px;
  transition: all 0.3s;
  position: relative;
  overflow: hidden;
}

/* Ripple effect */
.btn-add-cart::before {
  content: '';
  position: absolute;
  top: 50%;
  left: 50%;
  width: 0;
  height: 0;
  border-radius: 50%;
  background: rgba(255, 255, 255, 0.2);
  transform: translate(-50%, -50%);
  transition: width 0.6s, height 0.6s;
}

.btn-add-cart:hover::before {
  width: 300px;
  height: 300px;
}

/* Mobile: Icon only */
@media (max-width: 767px) {
  .btn-add-cart {
    width: 32px;
    height: 32px;
    font-size: 0;
    display: flex;
    align-items: center;
    justify-content: center;
  }
  
  .btn-add-cart i {
    font-size: 16px;
    margin: 0;
  }
}
```

### Cards

#### Product Card:
```css
.product-card {
  background: #fff;
  border: 1px solid #eee;
  border-radius: 8px;
  padding: 15px;
  transition: all 0.3s;
}

.product-card:hover {
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
  transform: translateY(-4px);
}

.product-card img {
  border-radius: 4px;
  width: 100%;
  height: auto;
}

.product-card .title {
  font-size: 14px;
  font-weight: 600;
  color: #333;
  margin: 12px 0 8px;
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

.product-card .price {
  font-size: 18px;
  font-weight: 700;
  color: var(--am-primary);
}
```

### Forms

#### Input Fields:
```css
.form-control {
  height: 48px;
  border: 1px solid #e0e0e0;
  border-radius: 8px;
  padding: 12px 16px;
  font-size: 14px;
  transition: all 0.3s;
}

.form-control:focus {
  border-color: var(--am-primary);
  box-shadow: 0 0 0 3px rgba(232, 102, 61, 0.1);
  outline: none;
}

.form-label {
  font-weight: 500;
  font-size: 14px;
  color: #333;
  margin-bottom: 8px;
  display: block;
}
```

#### Password Toggle:
```css
.password-toggle {
  position: relative;
}

.password-toggle .toggle-icon {
  position: absolute;
  right: 16px;
  top: 50%;
  transform: translateY(-50%);
  cursor: pointer;
  color: #999;
  font-size: 18px;
  transition: color 0.3s;
}

.password-toggle .toggle-icon:hover {
  color: var(--am-primary);
}
```

### Navigation

#### Main Header:
```css
.main-header {
  background: #fff;
  border-bottom: 1px solid #eee;
  height: 60px;
  position: sticky;
  top: 0;
  z-index: 1000;
}
```

#### Bottom Navigation:
```css
.bottom-bar {
  background: #fff;
  box-shadow: 0 -2px 15px rgba(0, 0, 0, 0.08);
  position: fixed;
  bottom: 0;
  left: 0;
  width: 100%;
  z-index: 9999;
}

.nav-item {
  text-align: center;
  font-size: 13px;
  color: #444;
  cursor: pointer;
  transition: all 0.3s;
}

.nav-item i {
  font-size: 20px;
  display: block;
  margin-bottom: 2px;
  transition: transform 0.2s;
}

.nav-item:hover i {
  color: var(--am-primary);
  transform: scale(1.15);
}
```

### Modals & Panels

#### Slide Panel:
```css
.slide-panel {
  position: fixed;
  bottom: 60px;
  left: 50%;
  transform: translateX(-50%) translateY(calc(100% + 60px));
  width: 92%;
  max-width: 360px;
  background: #fff;
  box-shadow: 0 5px 20px rgba(0, 0, 0, 0.2);
  border-radius: 10px;
  z-index: 10000;
  opacity: 0;
  transition: all 0.3s ease-in-out;
  overflow-y: auto;
  max-height: 70vh;
}

.slide-panel.show {
  transform: translateX(-50%) translateY(0);
  opacity: 1;
}
```

---

## 6. Layout System

### Grid System:
Uses Bootstrap 5 grid:
```html
<div class="container">
  <div class="row">
    <div class="col-12 col-md-6 col-lg-4">
      <!-- Content -->
    </div>
  </div>
</div>
```

### Container Widths:
```css
/* Bootstrap 5 defaults */
.container {
  max-width: 1320px;  /* XXL */
}

@media (max-width: 1399px) {
  .container { max-width: 1140px; }  /* XL */
}

@media (max-width: 1199px) {
  .container { max-width: 960px; }   /* LG */
}

@media (max-width: 991px) {
  .container { max-width: 720px; }   /* MD */
}

@media (max-width: 767px) {
  .container { max-width: 540px; }   /* SM */
}

@media (max-width: 575px) {
  .container { max-width: 100%; }    /* XS */
}
```

### Spacing System:
```css
/* Margins & Paddings */
.m-0 { margin: 0; }
.mt-1 { margin-top: 0.25rem; }
.mt-2 { margin-top: 0.5rem; }
.mt-3 { margin-top: 1rem; }
.mt-4 { margin-top: 1.5rem; }
.mt-5 { margin-top: 3rem; }

/* Same for mb (bottom), ml (left), mr (right) */
/* Same for p (padding) */
```

---

## 7. Responsive Breakpoints

### Breakpoint System:
```css
/* Extra Small (default) */
/* < 576px */

/* Small */
@media (min-width: 576px) { }

/* Medium */
@media (min-width: 768px) { }

/* Large */
@media (min-width: 992px) { }

/* Extra Large */
@media (min-width: 1200px) { }

/* XXL */
@media (min-width: 1400px) { }
```

### Mobile-First Approach:
```css
/* Base styles for mobile */
.element {
  font-size: 14px;
  padding: 10px;
}

/* Progressively enhance for larger screens */
@media (min-width: 768px) {
  .element {
    font-size: 16px;
    padding: 15px;
  }
}

@media (min-width: 992px) {
  .element {
    font-size: 18px;
    padding: 20px;
  }
}
```

### Common Responsive Patterns:

#### Stack to Row:
```css
.flex-container {
  display: flex;
  flex-direction: column;
}

@media (min-width: 768px) {
  .flex-container {
    flex-direction: row;
  }
}
```

#### Hide/Show Elements:
```css
/* Hide on mobile, show on desktop */
.desktop-only {
  display: none;
}

@media (min-width: 768px) {
  .desktop-only {
    display: block;
  }
}

/* Show on mobile, hide on desktop */
.mobile-only {
  display: block;
}

@media (min-width: 768px) {
  .mobile-only {
    display: none;
  }
}
```

#### Font Size Scaling:
```css
h1 {
  font-size: clamp(24px, 5vw, 32px);
}
```

---

## 8. Animation & Transitions

### Transition Speeds:
```css
:root {
  --transition-fast: 0.15s;
  --transition-normal: 0.3s;
  --transition-slow: 0.6s;
}
```

### Common Animations:

#### Fade In Up:
```css
@keyframes fadeInUp {
  from {
    opacity: 0;
    transform: translateY(20px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

.animate-fade-in-up {
  animation: fadeInUp 0.6s ease-out;
}
```

#### Slide Up:
```css
@keyframes slideUp {
  from {
    transform: translateY(100%);
    opacity: 0;
  }
  to {
    transform: translateY(0);
    opacity: 1;
  }
}

.animate-slide-up {
  animation: slideUp 0.4s ease-out forwards;
}
```

#### Ripple Effect:
```css
.ripple {
  position: relative;
  overflow: hidden;
}

.ripple::before {
  content: '';
  position: absolute;
  top: 50%;
  left: 50%;
  width: 0;
  height: 0;
  border-radius: 50%;
  background: rgba(255, 255, 255, 0.5);
  transform: translate(-50%, -50%);
  transition: width 0.6s, height 0.6s;
}

.ripple:active::before {
  width: 300px;
  height: 300px;
}
```

#### Hover Lift:
```css
.hover-lift {
  transition: transform 0.3s, box-shadow 0.3s;
}

.hover-lift:hover {
  transform: translateY(-4px);
  box-shadow: 0 8px 16px rgba(0, 0, 0, 0.1);
}
```

### Performance Optimizations:
```css
/* Use transform and opacity for animations */
/* These trigger GPU acceleration */
.optimized-animation {
  transform: translateZ(0);
  will-change: transform, opacity;
}
```

---

## 9. CSS File Organization

### components.css
**Purpose:** Core component styles  
**Content:**
- Variables and CSS custom properties
- Button styles
- Form elements
- Cards
- Modals
- Alerts
- Badges
- Navigation components
- Scroll-to-top button

### awesome-layout.css
**Purpose:** Page-specific layouts  
**Content:**
- Product details layout
- Gallery styles
- Buy box actions
- Review sections
- Accordion styles
- Product ribbons
- Trust signals

### awesome-extras.css
**Purpose:** Additional components  
**Content:**
- Duplicate/extended component styles
- Alternative button styles
- Extra card variations
- Additional utilities

### responsive.css
**Purpose:** Mobile adaptations  
**Content:**
- Mobile-specific overrides
- Breakpoint adjustments
- Touch-friendly sizing
- Mobile navigation
- Responsive typography
- Image scaling

### Design Tokens (variables.css):
```css
:root {
  /* Colors */
  --am-primary: #E8663D;
  --am-primary-hover: #d25532;
  --am-corporate-blue: #003A70;
  
  /* Spacing */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 32px;
  
  /* Border Radius */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-full: 9999px;
  
  /* Shadows */
  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.1);
  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
  --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
  
  /* Z-index Scale */
  --z-dropdown: 1000;
  --z-sticky: 1020;
  --z-fixed: 1030;
  --z-modal-backdrop: 1040;
  --z-modal: 1050;
  --z-popover: 1060;
  --z-tooltip: 1070;
}
```

---

## 10. Best Practices

### CSS Writing Guidelines:

#### 1. Use Meaningful Class Names:
```css
/* Good */
.product-card { }
.btn-primary { }
.cart-summary { }

/* Bad */
.box1 { }
.red-button { }
.thing { }
```

#### 2. Avoid Over-Specificity:
```css
/* Good */
.btn-primary { }

/* Bad */
div.container .row .col .btn-primary { }
```

#### 3. Group Related Properties:
```css
.element {
  /* Positioning */
  position: absolute;
  top: 0;
  left: 0;
  z-index: 10;
  
  /* Box Model */
  display: flex;
  width: 100%;
  padding: 16px;
  margin: 8px;
  
  /* Typography */
  font-size: 14px;
  font-weight: 600;
  color: #333;
  
  /* Visual */
  background: #fff;
  border: 1px solid #eee;
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
  
  /* Animation */
  transition: all 0.3s;
}
```

#### 4. Use CSS Variables:
```css
/* Good */
.btn-primary {
  background: var(--am-primary);
}

/* Less flexible */
.btn-primary {
  background: #E8663D;
}
```

#### 5. Mobile-First Media Queries:
```css
/* Good - Mobile first */
.element {
  font-size: 14px;
}

@media (min-width: 768px) {
  .element {
    font-size: 16px;
  }
}

/* Less ideal - Desktop first */
.element {
  font-size: 16px;
}

@media (max-width: 767px) {
  .element {
    font-size: 14px;
  }
}
```

### Performance Best Practices:

#### 1. Minimize Repaints:
```css
/* Use transform instead of top/left */
.animate {
  transform: translateY(10px);
  /* Not: top: 10px; */
}
```

#### 2. Avoid Universal Selectors:
```css
/* Avoid */
* { box-sizing: border-box; }

/* Better */
html { box-sizing: border-box; }
*, *::before, *::after { box-sizing: inherit; }
```

#### 3. Lazy Load Non-Critical CSS:
```html
<link rel="preload" href="critical.css" as="style">
<link rel="stylesheet" href="non-critical.css" media="print" onload="this.media='all'">
```

### Accessibility Guidelines:

#### 1. Color Contrast:
- Minimum 4.5:1 for normal text
- Minimum 3:1 for large text
- Test with tools like WebAIM

#### 2. Focus States:
```css
.btn:focus {
  outline: 2px solid var(--am-primary);
  outline-offset: 2px;
}
```

#### 3. Reduced Motion:
```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
```

---

## 📊 Component Inventory

### UI Components List:
1. Buttons (Primary, Secondary, Add-to-cart, Icon)
2. Forms (Input, Textarea, Select, Checkbox, Radio)
3. Cards (Product, Info, Feature)
4. Navigation (Header, Bottom Bar, Breadcrumbs)
5. Modals & Panels (Slide-in, Full-screen)
6. Alerts & Notifications
7. Badges & Tags
8. Progress Bars & Indicators
9. Tables
10. Accordions
11. Tabs
12. Carousels
13. Tooltips & Popovers
14. Pagination
15. Search Components

### Page Templates:
1. Homepage
2. Product Listing (Category)
3. Product Detail
4. Cart
5. Checkout
6. User Account
7. Login/Signup
8. Order History
9. Wishlist
10. Search Results

---

**End of Styling Documentation**  
**Last Updated:** January 13, 2026
