# Design System - How to Malaysia Website

## Brand Identity & Visual Language

### Brand Positioning
**Mission:** Empowering everyone to navigate Malaysia with confidence through clear, accessible, and culturally-sensitive guidance.

**Brand Personality:**
- **Helpful & Approachable:** Friendly guidance without condescension
- **Trustworthy & Accurate:** Reliable information from verified sources  
- **Culturally Aware:** Respectful of Malaysia's diverse communities
- **Modern & Accessible:** Contemporary design with universal usability

### Visual Inspiration
**Malaysian Cultural Elements:**
- Traditional batik patterns (subtle background textures)
- Tropical colors inspired by Malaysian flora and fauna
- Modern Malaysian architecture (clean lines, functional beauty)
- Multicultural harmony (balanced, inclusive imagery)

---

## Color System

### Primary Color Palette

#### Malaysia-Inspired Core Colors
```css
/* Primary Blues - Trust, Stability, Government */
--primary-blue: #003366;     /* Malaysian Flag Blue - Deep Navy */
--primary-blue-light: #1e4d6b;
--primary-blue-lighter: #4a90c2;

/* Accent Red - Energy, Important Actions */
--accent-red: #cc0000;       /* Malaysian Flag Red */
--accent-red-light: #e53e3e;
--accent-red-lighter: #feb2b2;

/* Success Green - Completion, Nature */
--success-green: #2d5016;    /* Malaysian Rainforest Green */
--success-green-light: #38a169;
--success-green-lighter: #9ae6b4;

/* Warning Gold - Caution, Attention */
--warning-gold: #d69e2e;     /* Malaysian Gold/Yellow */
--warning-gold-light: #ecc94b;
--warning-gold-lighter: #faf089;
```

#### Neutral Color System
```css
/* Neutral Grays - Text, Backgrounds */
--gray-900: #1a202c;         /* Primary Text */
--gray-800: #2d3748;         /* Secondary Text */
--gray-700: #4a5568;         /* Muted Text */
--gray-600: #718096;         /* Placeholder Text */
--gray-500: #a0aec0;         /* Borders, Dividers */
--gray-400: #cbd5e0;         /* Light Borders */
--gray-300: #e2e8f0;         /* Background Borders */
--gray-200: #edf2f7;         /* Light Backgrounds */
--gray-100: #f7fafc;         /* Subtle Backgrounds */
--gray-50: #fafbfc;          /* Page Background */

/* Pure Colors */
--white: #ffffff;
--black: #000000;
```

#### Semantic Color Applications
```css
/* Status Colors */
--color-success: var(--success-green);
--color-warning: var(--warning-gold);
--color-error: var(--accent-red);
--color-info: var(--primary-blue-lighter);

/* Interactive Colors */
--color-link: var(--primary-blue);
--color-link-hover: var(--primary-blue-light);
--color-button-primary: var(--primary-blue);
--color-button-secondary: var(--gray-600);
--color-button-danger: var(--accent-red);

/* Background Colors */
--bg-primary: var(--white);
--bg-secondary: var(--gray-50);
--bg-accent: var(--gray-100);
--bg-dark: var(--gray-900);
```

### Color Usage Guidelines
- **Primary Blue:** Navigation, headers, primary CTAs, trust elements
- **Accent Red:** Urgent information, warnings, important CTAs  
- **Success Green:** Completion states, positive feedback, nature content
- **Warning Gold:** Caution messages, tips, highlights
- **Neutral Grays:** Text hierarchy, backgrounds, subtle UI elements

---

## Typography System

### Font Families

#### Primary Typeface: Inter
```css
/* Clean, highly legible sans-serif optimized for UI */
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;

/* Features: */
- Excellent readability at all sizes
- Strong multilingual support (Latin, Cyrillic)
- Optimized for digital screens
- Professional, modern appearance
```

#### Secondary Typeface: Noto Sans
```css
/* For multilingual content - Bahasa Malaysia, Chinese characters */
font-family: 'Noto Sans', 'Noto Sans CJK SC', sans-serif;

/* Features: */
- Comprehensive language support
- Consistent design across scripts
- Google Fonts availability
- Harmonious with Inter
```

#### Monospace: JetBrains Mono
```css
/* For code snippets, forms, technical content */
font-family: 'JetBrains Mono', 'Monaco', 'Menlo', monospace;
```

### Typography Scale & Hierarchy

#### Font Size Scale (Fluid Typography)
```css
/* Base font size: 16px */
--font-size-xs: 0.75rem;     /* 12px - Captions, fine print */
--font-size-sm: 0.875rem;    /* 14px - Small text, meta info */
--font-size-base: 1rem;      /* 16px - Body text, paragraph */
--font-size-lg: 1.125rem;    /* 18px - Large body text */
--font-size-xl: 1.25rem;     /* 20px - Subheadings */
--font-size-2xl: 1.5rem;     /* 24px - H4 */
--font-size-3xl: 1.875rem;   /* 30px - H3 */
--font-size-4xl: 2.25rem;    /* 36px - H2 */
--font-size-5xl: 3rem;       /* 48px - H1 */
--font-size-6xl: 3.75rem;    /* 60px - Display headings */
```

#### Text Styles & Usage
```css
/* Headings */
.heading-1 {
  font-size: var(--font-size-5xl);
  font-weight: 700;
  line-height: 1.1;
  letter-spacing: -0.025em;
  color: var(--gray-900);
}

.heading-2 {
  font-size: var(--font-size-4xl);
  font-weight: 600;
  line-height: 1.2;
  letter-spacing: -0.025em;
  color: var(--gray-900);
}

.heading-3 {
  font-size: var(--font-size-3xl);
  font-weight: 600;
  line-height: 1.3;
  color: var(--gray-900);
}

/* Body Text */
.body-large {
  font-size: var(--font-size-lg);
  font-weight: 400;
  line-height: 1.6;
  color: var(--gray-800);
}

.body-text {
  font-size: var(--font-size-base);
  font-weight: 400;
  line-height: 1.6;
  color: var(--gray-800);
}

.body-small {
  font-size: var(--font-size-sm);
  font-weight: 400;
  line-height: 1.5;
  color: var(--gray-700);
}

/* Specialized Text */
.text-meta {
  font-size: var(--font-size-sm);
  font-weight: 500;
  color: var(--gray-600);
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

.text-emphasis {
  font-weight: 600;
  color: var(--primary-blue);
}

.text-warning {
  font-weight: 500;
  color: var(--accent-red);
}
```

---

## Layout & Spacing System

### Grid System
```css
/* Container Sizes */
--container-sm: 640px;     /* Small screens */
--container-md: 768px;     /* Medium screens */
--container-lg: 1024px;    /* Large screens */
--container-xl: 1280px;    /* Extra large screens */
--container-2xl: 1536px;   /* 2X large screens */

/* Content Width */
--content-width: 65ch;     /* Optimal reading width */
--sidebar-width: 280px;    /* Sidebar/navigation width */
```

### Spacing Scale
```css
/* 8px base unit spacing system */
--space-px: 1px;
--space-0: 0;
--space-1: 0.25rem;  /* 4px */
--space-2: 0.5rem;   /* 8px */
--space-3: 0.75rem;  /* 12px */
--space-4: 1rem;     /* 16px */
--space-5: 1.25rem;  /* 20px */
--space-6: 1.5rem;   /* 24px */
--space-8: 2rem;     /* 32px */
--space-10: 2.5rem;  /* 40px */
--space-12: 3rem;    /* 48px */
--space-16: 4rem;    /* 64px */
--space-20: 5rem;    /* 80px */
--space-24: 6rem;    /* 96px */
--space-32: 8rem;    /* 128px */
```

### Layout Components
```css
/* Article Content Layout */
.article-layout {
  display: grid;
  grid-template-columns: 1fr min(65ch, 100%) 1fr;
  grid-template-areas: 
    ". header ."
    ". content ."
    ". footer .";
  gap: var(--space-8);
}

/* Two-Column Layout */
.two-column {
  display: grid;
  grid-template-columns: 280px 1fr;
  gap: var(--space-8);
}

/* Card Grid */
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: var(--space-6);
}
```

---

## Component Design System

### Buttons

#### Button Variants
```css
/* Primary Button */
.btn-primary {
  background: var(--primary-blue);
  color: white;
  padding: var(--space-3) var(--space-6);
  border-radius: 6px;
  font-weight: 600;
  font-size: var(--font-size-base);
  border: none;
  cursor: pointer;
  transition: all 0.2s ease;
}

.btn-primary:hover {
  background: var(--primary-blue-light);
  transform: translateY(-1px);
}

/* Secondary Button */
.btn-secondary {
  background: transparent;
  color: var(--primary-blue);
  border: 2px solid var(--primary-blue);
  padding: var(--space-3) var(--space-6);
  border-radius: 6px;
  font-weight: 600;
}

/* Danger Button */
.btn-danger {
  background: var(--accent-red);
  color: white;
}

/* Small Button */
.btn-sm {
  padding: var(--space-2) var(--space-4);
  font-size: var(--font-size-sm);
}

/* Large Button */
.btn-lg {
  padding: var(--space-4) var(--space-8);
  font-size: var(--font-size-lg);
}
```

### Cards & Content Blocks

#### Article Card
```css
.article-card {
  background: white;
  border: 1px solid var(--gray-300);
  border-radius: 12px;
  overflow: hidden;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
  transition: all 0.3s ease;
}

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

.article-card-image {
  width: 100%;
  height: 200px;
  object-fit: cover;
}

.article-card-content {
  padding: var(--space-6);
}

.article-card-title {
  font-size: var(--font-size-xl);
  font-weight: 600;
  color: var(--gray-900);
  margin-bottom: var(--space-2);
}

.article-card-excerpt {
  color: var(--gray-700);
  line-height: 1.5;
  margin-bottom: var(--space-4);
}

.article-card-meta {
  display: flex;
  justify-content: space-between;
  align-items: center;
  font-size: var(--font-size-sm);
  color: var(--gray-600);
}
```

#### Info Callout Boxes
```css
/* Tips Callout */
.callout-tip {
  background: #f0f9ff;
  border-left: 4px solid var(--primary-blue);
  padding: var(--space-4);
  border-radius: 0 6px 6px 0;
  margin: var(--space-6) 0;
}

/* Warning Callout */
.callout-warning {
  background: #fffbeb;
  border-left: 4px solid var(--warning-gold);
  padding: var(--space-4);
  border-radius: 0 6px 6px 0;
}

/* Important Callout */
.callout-important {
  background: #fef2f2;
  border-left: 4px solid var(--accent-red);
  padding: var(--space-4);
  border-radius: 0 6px 6px 0;
}
```

### Navigation Components

#### Main Navigation
```css
.main-nav {
  background: white;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
  position: sticky;
  top: 0;
  z-index: 100;
}

.nav-item {
  padding: var(--space-4) var(--space-6);
  color: var(--gray-700);
  text-decoration: none;
  font-weight: 500;
  transition: color 0.2s ease;
}

.nav-item:hover {
  color: var(--primary-blue);
}

.nav-item.active {
  color: var(--primary-blue);
  border-bottom: 2px solid var(--primary-blue);
}
```

#### Breadcrumb Navigation
```css
.breadcrumb {
  display: flex;
  align-items: center;
  gap: var(--space-2);
  margin-bottom: var(--space-6);
  font-size: var(--font-size-sm);
}

.breadcrumb-item {
  color: var(--gray-600);
}

.breadcrumb-item:not(:last-child)::after {
  content: ">";
  margin-left: var(--space-2);
  color: var(--gray-500);
}

.breadcrumb-item.current {
  color: var(--gray-900);
  font-weight: 500;
}
```

### Form Elements

#### Input Fields
```css
.form-input {
  width: 100%;
  padding: var(--space-3);
  border: 1px solid var(--gray-400);
  border-radius: 6px;
  font-size: var(--font-size-base);
  transition: border-color 0.2s ease;
}

.form-input:focus {
  outline: none;
  border-color: var(--primary-blue);
  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
}

.form-label {
  display: block;
  margin-bottom: var(--space-2);
  font-weight: 600;
  color: var(--gray-900);
}

.form-error {
  color: var(--accent-red);
  font-size: var(--font-size-sm);
  margin-top: var(--space-1);
}
```

#### Search Bar
```css
.search-container {
  position: relative;
  max-width: 400px;
}

.search-input {
  width: 100%;
  padding: var(--space-3) var(--space-12) var(--space-3) var(--space-4);
  border: 2px solid var(--gray-300);
  border-radius: 24px;
  font-size: var(--font-size-base);
}

.search-icon {
  position: absolute;
  right: var(--space-4);
  top: 50%;
  transform: translateY(-50%);
  color: var(--gray-500);
}
```

---

## Responsive Design System

### Breakpoint Strategy
```css
/* Mobile First Approach */
--breakpoint-sm: 640px;   /* Small devices */
--breakpoint-md: 768px;   /* Medium devices */
--breakpoint-lg: 1024px;  /* Large devices */
--breakpoint-xl: 1280px;  /* Extra large devices */
--breakpoint-2xl: 1536px; /* 2X large devices */
```

### Component Responsive Behavior
```css
/* Navigation - Mobile */
@media (max-width: 768px) {
  .main-nav {
    flex-direction: column;
  }
  
  .nav-item {
    padding: var(--space-3) var(--space-4);
    border-bottom: 1px solid var(--gray-200);
  }
}

/* Card Grid - Responsive */
@media (max-width: 640px) {
  .card-grid {
    grid-template-columns: 1fr;
  }
}

@media (min-width: 768px) {
  .card-grid {
    grid-template-columns: repeat(2, 1fr);
  }
}

@media (min-width: 1024px) {
  .card-grid {
    grid-template-columns: repeat(3, 1fr);
  }
}
```

---

## Accessibility & Inclusive Design

### Color Accessibility
- **Contrast Ratios:** Minimum 4.5:1 for normal text, 3:1 for large text
- **Color Independence:** No information conveyed by color alone
- **High Contrast Mode:** Support for Windows high contrast mode

### Focus Management
```css
/* Focus Indicators */
.focusable:focus {
  outline: 2px solid var(--primary-blue);
  outline-offset: 2px;
}

/* Skip Links */
.skip-link {
  position: absolute;
  top: -40px;
  left: 6px;
  background: var(--primary-blue);
  color: white;
  padding: 8px;
  text-decoration: none;
  transition: top 0.3s;
}

.skip-link:focus {
  top: 6px;
}
```

### Screen Reader Support
- **Semantic HTML:** Proper heading hierarchy, landmarks
- **ARIA Labels:** Descriptive labels for interactive elements
- **Alt Text:** Meaningful descriptions for images
- **Live Regions:** Dynamic content announcements

---

## Animation & Micro-interactions

### Transition Standards
```css
/* Standard Transitions */
--transition-fast: 0.15s ease;
--transition-normal: 0.3s ease;
--transition-slow: 0.5s ease;

/* Common Animations */
.fade-in {
  animation: fadeIn 0.3s ease-in;
}

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

@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes slideUp {
  from { 
    opacity: 0; 
    transform: translateY(20px); 
  }
  to { 
    opacity: 1; 
    transform: translateY(0); 
  }
}

/* Hover Effects */
.hover-lift {
  transition: transform 0.2s ease;
}

.hover-lift:hover {
  transform: translateY(-2px);
}
```

### Loading States
```css
.loading-spinner {
  width: 24px;
  height: 24px;
  border: 2px solid var(--gray-300);
  border-top: 2px solid var(--primary-blue);
  border-radius: 50%;
  animation: spin 1s linear infinite;
}

@keyframes spin {
  0% { transform: rotate(0deg); }
  100% { transform: rotate(360deg); }
}
```

---

## Implementation Guidelines

### CSS Architecture
- **Utility-first approach** with component classes
- **CSS Custom Properties** for theming and consistency
- **Progressive enhancement** for advanced features
- **Component-scoped styles** to avoid conflicts

### Design Token Management
```css
/* Design Tokens File: tokens.css */
:root {
  /* Colors */
  --primary-blue: #003366;
  /* ... all design tokens ... */
  
  /* Spacing */
  --space-4: 1rem;
  /* ... spacing scale ... */
  
  /* Typography */
  --font-size-base: 1rem;
  /* ... typography scale ... */
}

/* Dark mode tokens */
@media (prefers-color-scheme: dark) {
  :root {
    --bg-primary: var(--gray-900);
    --text-primary: var(--gray-100);
    /* ... dark mode overrides ... */
  }
}
```

### Quality Assurance
- **Cross-browser testing:** Chrome, Firefox, Safari, Edge
- **Device testing:** Mobile, tablet, desktop across different screen sizes
- **Accessibility auditing:** WAVE, axe-core, manual testing
- **Performance monitoring:** Lighthouse, Core Web Vitals

---

**Design System Owner:** [UI/UX Designer Name]  
**Last Updated:** October 12, 2025  
**Version:** 1.0.0  
**Status:** Foundation Complete - Ready for Implementation