# Master Design System & AI Context Blueprint

**Project:** Bangladesh Saree E-Commerce Website  
**Purpose of This Document:** High-level architectural overview for AI-assisted UI/UX and frontend implementation.  
**Token & Standards References:**  
* **All Color & Font Token Values:** `global_color_typography_design_plan.md` (the **only** file containing hex codes and font family names).  
* **All Shared UI Component & Content Rules:** `global_ui_components_and_content_standards.md`.  
* **Step-by-Step Frontend Build Sequence:** `00_frontend_master_workflow_and_build_order.md`.

---

## 1. Core Project Rules (Read First)

1. **100% Variable-Driven Styling:** Never hardcode hex values or font names inside any component or page stylesheet. Strictly use the **12 Global CSS Variables**:
   * **Surfaces & Brand (80-15-5 Rule):** `--bg-main`, `--bg-surface`, `--brand-primary`, `--brand-accent`, `--border-subtle`
   * **Typography Colors:** `--text-primary`, `--text-muted`, `--text-light`
   * **State Colors:** `--state-success`, `--state-error`
   * **Font Variables:** `--font-heading`, `--font-body`
2. **Contrast & Hover Rule:** Whenever `--brand-accent` is used as a background fill (e.g., `ORDER NOW`, `QUICK VIEW`, `CONFIRM ORDER`, discount/new badges, cart counter), its text color must **always** be `--text-primary` (never `--text-light`). On hover or tap, `--brand-accent` buttons flip their background to `--brand-primary` and text to `--text-light`.
3. **Bangladesh Market & Mobile-First Context:**
   * Over 85% of shoppers browse on smartphones (`320px – 767px`); every layout is designed Mobile-First.
   * Prices are always displayed in clean whole numbers in Bangladeshi Taka (`BDT 4,500`), never with decimals.
   * **100% Guest Checkout with Cash on Delivery (COD) Only** (no account creation required, plus an **Optional Email Field** for order confirmation and shipping tracking emails).
4. **English-Only Interface:** The entire website uses English exclusively.
5. **Zero Header & Card Clutter:** No wishlist heart icons (`♡`), no header search bar, no header track-order link, no login icon, and no `All Sarees ▾` dropdown menu.
6. **Future-Proof Scalability:** Phase 1 sells **Sarees only** (*Jamdani, Muslin, Katan, Silk, Cotton, Tangail*). Phase 2 will expand to other women's items (*Salwar Kameez, Kurtis, Dupattas, Jewelry*) using the exact same reusable templates.

---

## 2. Established Component & Page Design Patterns

1. **Global Header & Footer (`global_header_and_footer_plan.md`):**
   * Anchors the **15% `--brand-primary` zone** with `--text-light` text/icons and `--brand-accent` highlights.
   * Supports two switchable navigation modes in `storeConfig`: **`MODE_A` (Flat Direct Saree Category Bar)** and **`MODE_B` (Minimal Boutique Bar)**, plus a Left Slide-Out Mobile Menu Drawer and Right Shopping Bag trigger.
2. **Global Product Card & Responsive Sliders (`all_sarees_category_showcase_plan.md` & `global_ui_components_and_content_standards.md`):**
   * Strict **`3:4` vertical portrait** image inside a `--bg-surface` frame with `1px` `--border-subtle` border.
   * Desktop hover (or Mobile 1st tap on image) transitions **Image 1 → Image 2 (Aanchal closeup)** and slides up the **`QUICK VIEW`** bar (`--brand-accent` fill with `--text-primary` text). Mobile 2nd tap on image (or 1st tap on title/price) opens the PDP.
   * **Responsive Sliders:** Desktop shows **4 cards + arrows + 3-Dot Navigation**; Mobile (`320–767px`) shows **2 cards + ~10% peek + touch swipe + Slim Progress Bar + "View All →" End Card**.
3. **Homepage 8-Section Boutique Flow (`homepage_layout_and_section_flow_plan.md`):**
   * 1. Editorial Split Hero (Desktop `4:3` / Mobile uncropped `4:5` Portrait) → 2. Shop by Saree Weave (`3:4` Portrait Cards) → 3. New Arrivals Slider → 4. Festive & Bridal Spotlight Banner → 5. Most Loved (Best Sellers) Slider → 6. 4 Non-Overlapping Budget Tiles → 7. Customer Drape Stories (Verified Photo Reviews) → 8. All Collections Gateway CTA & 4-Pillar Bangladesh Trust Strip.
4. **Single Category & Collection Listing Pages (`single_category_view_all_page_plan.md` & `collection_and_utility_pages_plan.md`):**
   * Compact header with Quick Switcher Pills, static Top Filter & Sort Bar (Desktop dropdowns / Mobile Filter Bottom Sheet) synced with URL query params, 12-item batch infinite scroll with warm shimmer skeletons (`--bg-surface` / `--border-subtle`), Scroll Memory, and Floating Back-to-Top (`↑`) button.
5. **Quick View Modal (`quick_view_modal_page_plan.md`):**
   * Desktop centered 2-column modal (`920px`, `50% / 50%` split) / Mobile Slide-Up Bottom Sheet (`88dvh`). Features `3:4` photo slider, `2×2` Quick Highlights Box, Quantity stepper, `ADD TO CART` + `ORDER NOW` (Express Buy), and `View Full Product Details →`.
6. **Product Details Page — PDP (`product_details_page_pdp_plan.md` & `reviews_chat_and_social_sharing_plan.md`):**
   * `3:4` multi-angle gallery with `2.5×` desktop weave magnifier and mobile pinch-to-zoom lightbox, sticky right info column, `2×2` highlights grid, `ADD TO CART` + `ORDER NOW`, Bangladesh COD Trust Box, Social Share row (WhatsApp, Facebook, Copy Link + Open Graph meta tags), 3 Spec/Care Accordions, **Customer Reviews & Photos section** (with `Write a Review` modal), Related Sarees sliders, and **Mobile Sticky Bottom Conversion Bar**.
7. **Slide-Out Cart Drawer & Single-Page Guest COD Checkout (`cart_and_checkout_flow_plan.md`):**
   * Right Cart Drawer for multi-item bag review; **Express Buy (`ORDER NOW`)** checks out only the selected saree while keeping existing bag items untouched (with a 1-tap `"+ Add them to this order"` strip).
   * 1-Page Guest Checkout with Mobile Collapsible Order Summary, 11-digit BD mobile validation, **Optional Email Field** (for order confirmation & shipping tracking emails), Inside Dhaka (`BDT 70`) / Outside Dhaka (`BDT 130`) radio cards, Cash on Delivery confirmation, and `/order-received/[orderId]` view.
8. **Floating WhatsApp / Messenger Assist (`reviews_chat_and_social_sharing_plan.md`):**
   * Brand-harmonized (`--brand-primary` / `--brand-accent`) bottom-right chat button with context-aware pre-filled messages, automatically shifting above the PDP Mobile Sticky Bar and hiding when drawers/modals or `/checkout` are active.

---

## 3. Complete Design Documentation Index (All 14 Files)

* [x] **00.** [00_frontend_master_workflow_and_build_order.md](file:///d:/Google%20Drive/Angina%20Website/00_frontend_master_workflow_and_build_order.md) — *Master Entry Point & Step-by-Step Build Order*
* [x] **01.** [master_design_system_ai_context_blueprint.md](file:///d:/Google%20Drive/Angina%20Website/master_design_system_ai_context_blueprint.md) — *High-Level Context Blueprint (This File)*
* [x] **02.** [global_color_typography_design_plan.md](file:///d:/Google%20Drive/Angina%20Website/global_color_typography_design_plan.md) — *12 Master Color & Typography Tokens*
* [x] **03.** [global_ui_components_and_content_standards.md](file:///d:/Google%20Drive/Angina%20Website/global_ui_components_and_content_standards.md) — *Shared UI Standards, Sliders, Badges, Express Buy & Layering*
* [x] **04.** [future_admin_controls_and_dynamic_frontend_notes.md](file:///d:/Google%20Drive/Angina%20Website/future_admin_controls_and_dynamic_frontend_notes.md) — *Central `storeConfig` & Mock Data Schema Notes*
* [x] **05.** [global_header_and_footer_plan.md](file:///d:/Google%20Drive/Angina%20Website/global_header_and_footer_plan.md) — *Dual-Mode Header (`MODE_A` & `MODE_B`), Mobile Drawer & Footer*
* [x] **06.** [all_sarees_category_showcase_plan.md](file:///d:/Google%20Drive/Angina%20Website/all_sarees_category_showcase_plan.md) — *"All Sarees" Hub & Global Product Card Rules*
* [x] **07.** [single_category_view_all_page_plan.md](file:///d:/Google%20Drive/Angina%20Website/single_category_view_all_page_plan.md) — *Single Category Listing, Filters, Shimmer & Scroll Memory*
* [x] **08.** [quick_view_modal_page_plan.md](file:///d:/Google%20Drive/Angina%20Website/quick_view_modal_page_plan.md) — *Quick View Modal (Desktop `920px` Split / Mobile Bottom Sheet)*
* [x] **09.** [homepage_layout_and_section_flow_plan.md](file:///d:/Google%20Drive/Angina%20Website/homepage_layout_and_section_flow_plan.md) — *8-Section Boutique Homepage Flow*
* [x] **10.** [product_details_page_pdp_plan.md](file:///d:/Google%20Drive/Angina%20Website/product_details_page_pdp_plan.md) — *Product Details Page (PDP), Weave Zoom & Mobile Sticky Bar*
* [x] **11.** [cart_and_checkout_flow_plan.md](file:///d:/Google%20Drive/Angina%20Website/cart_and_checkout_flow_plan.md) — *Slide-Out Cart Drawer & 1-Page Guest COD Checkout*
* [x] **12.** [collection_and_utility_pages_plan.md](file:///d:/Google%20Drive/Angina%20Website/collection_and_utility_pages_plan.md) — *Complete Route Map, Curated Collections, Policy Pages & 404*
* [x] **13.** [reviews_chat_and_social_sharing_plan.md](file:///d:/Google%20Drive/Angina%20Website/reviews_chat_and_social_sharing_plan.md) — *Customer Reviews, Floating WhatsApp/Messenger Chat & Open Graph Share*
* [x] **14.** [tech_stack_and_build_setup_plan.md](file:///d:/Google%20Drive/Aangina%20Website/frontend/tech_stack_and_build_setup_plan.md) — *Finalized Tech Stack (Laravel 11 + Blade + Tailwind CSS Strictly Mapped to 12 `:root` Variables + Alpine.js)*
* [x] **15.** [../backend/00_backend_and_erp_master_plan.md](file:///d:/Google%20Drive/Aangina%20Website/backend/00_backend_and_erp_master_plan.md) — *Two-Stage Backend & Saree ERP Master Plan*