diff --git a/design/marketplace-search/README.md b/design/marketplace-search/README.md
new file mode 100644
index 0000000..4f43574
--- /dev/null
+++ b/design/marketplace-search/README.md
@@ -0,0 +1,77 @@
+# 🔍 Marketplace Search UX Design
+
+## Purpose
+This folder contains comprehensive UI/UX design documentation for the **Marketplace Search system** in CommitLabs.
+
+The objective is to create a **fast, intuitive, and low-friction search experience** that helps users quickly discover commitments within the marketplace.
+
+This design focuses on:
+- Search input behavior and placement
+- Typeahead (autocomplete) suggestions
+- Recent searches
+- Empty and no-result states
+- Accessibility and mobile responsiveness
+
+---
+
+## 🎯 Goals
+- Enable quick discovery of commitments
+- Reduce user effort when searching
+- Provide helpful suggestions and guidance
+- Handle edge cases (no results, errors) gracefully
+- Maintain consistency across dashboard and marketplace
+
+---
+
+## 📦 What is Included
+
+### 1. Search UI Components
+- Search bar (desktop and mobile)
+- Search icon and input states
+- Clear (reset) action
+- Focus and active states
+
+### 2. Typeahead System
+- Real-time suggestions as user types
+- Suggested matches (titles, tags, categories)
+- Keyboard navigation support
+
+### 3. Recent Searches
+- Previously searched queries
+- Quick re-selection behavior
+- Clear history option (optional)
+
+### 4. Empty & No Results States
+- Empty search (no input yet)
+- No matching results
+- Helpful fallback suggestions
+
+### 5. Mobile Behavior
+- Full-width search interaction
+- Touch-friendly input and suggestions
+- Optimized spacing and readability
+
+### 6. Accessibility Considerations
+- Keyboard navigation (↑ ↓ Enter Esc)
+- Screen reader support
+- Clear focus states
+- Sufficient contrast and readable text
+
+---
+
+##  Design Principles
+- **Clarity first** — user always understands what is happening
+- **Speed** — minimize time to result
+- **Guidance** — suggest instead of forcing users to guess
+- **Consistency** — same behavior across all entry points
+- **Accessibility** — usable by all users
+
+---
+
+##  Reference Design (Figma)
+Paste your design link below:
+
+👉 **Figma Link:**  
+https://www.figma.com/design/P3YGg95rHCVCrI4TP1DVo3/CommitLabs-Search-Pattern?node-id=0-1&t=Q2Iwl6ne79QiBSJp-1 
+
+---
diff --git a/design/marketplace-search/screens/hi-fidelity/State 1 Default.png b/design/marketplace-search/screens/hi-fidelity/State 1 Default.png
new file mode 100644
index 0000000..6c3b3dc
Binary files /dev/null and b/design/marketplace-search/screens/hi-fidelity/State 1 Default.png differ
diff --git a/design/marketplace-search/screens/hi-fidelity/State 1 no query (landing).png b/design/marketplace-search/screens/hi-fidelity/State 1 no query (landing).png
new file mode 100644
index 0000000..2a93793
Binary files /dev/null and b/design/marketplace-search/screens/hi-fidelity/State 1 no query (landing).png differ
diff --git a/design/marketplace-search/screens/hi-fidelity/State 2 Recent searches.png b/design/marketplace-search/screens/hi-fidelity/State 2 Recent searches.png
new file mode 100644
index 0000000..d6c7678
Binary files /dev/null and b/design/marketplace-search/screens/hi-fidelity/State 2 Recent searches.png differ
diff --git a/design/marketplace-search/screens/hi-fidelity/State 3Typehead.png b/design/marketplace-search/screens/hi-fidelity/State 3Typehead.png
new file mode 100644
index 0000000..27586ce
Binary files /dev/null and b/design/marketplace-search/screens/hi-fidelity/State 3Typehead.png differ
diff --git a/design/marketplace-search/screens/hi-fidelity/State 4 Acive query.png b/design/marketplace-search/screens/hi-fidelity/State 4 Acive query.png
new file mode 100644
index 0000000..68da776
Binary files /dev/null and b/design/marketplace-search/screens/hi-fidelity/State 4 Acive query.png differ
diff --git a/design/marketplace-search/screens/hi-fidelity/State 5 Empty.png b/design/marketplace-search/screens/hi-fidelity/State 5 Empty.png
new file mode 100644
index 0000000..475a5c5
Binary files /dev/null and b/design/marketplace-search/screens/hi-fidelity/State 5 Empty.png differ
diff --git a/design/marketplace-search/screens/hi-fidelity/state 2_ focused with recent searches.png b/design/marketplace-search/screens/hi-fidelity/state 2_ focused with recent searches.png
new file mode 100644
index 0000000..f349d04
Binary files /dev/null and b/design/marketplace-search/screens/hi-fidelity/state 2_ focused with recent searches.png differ
diff --git a/design/marketplace-search/screens/hi-fidelity/state 3_ typeahead suggestions (user typed _hel_).png b/design/marketplace-search/screens/hi-fidelity/state 3_ typeahead suggestions (user typed _hel_).png
new file mode 100644
index 0000000..715e0d6
Binary files /dev/null and b/design/marketplace-search/screens/hi-fidelity/state 3_ typeahead suggestions (user typed _hel_).png differ
diff --git a/design/marketplace-search/screens/hi-fidelity/state 4_ results with active search query.png b/design/marketplace-search/screens/hi-fidelity/state 4_ results with active search query.png
new file mode 100644
index 0000000..3115668
Binary files /dev/null and b/design/marketplace-search/screens/hi-fidelity/state 4_ results with active search query.png differ
diff --git a/design/marketplace-search/screens/hi-fidelity/state 5_ empty results (no match found).png b/design/marketplace-search/screens/hi-fidelity/state 5_ empty results (no match found).png
new file mode 100644
index 0000000..8b155b3
Binary files /dev/null and b/design/marketplace-search/screens/hi-fidelity/state 5_ empty results (no match found).png differ
diff --git a/design/marketplace-search/screens/wireframes/Empty results state.png b/design/marketplace-search/screens/wireframes/Empty results state.png
new file mode 100644
index 0000000..769bbbb
Binary files /dev/null and b/design/marketplace-search/screens/wireframes/Empty results state.png differ
diff --git a/design/marketplace-search/screens/wireframes/Empty state.png b/design/marketplace-search/screens/wireframes/Empty state.png
new file mode 100644
index 0000000..1e16f74
Binary files /dev/null and b/design/marketplace-search/screens/wireframes/Empty state.png differ
diff --git a/design/marketplace-search/screens/wireframes/Focus-recent search.png b/design/marketplace-search/screens/wireframes/Focus-recent search.png
new file mode 100644
index 0000000..1d7fde2
Binary files /dev/null and b/design/marketplace-search/screens/wireframes/Focus-recent search.png differ
diff --git a/design/marketplace-search/screens/wireframes/Focused (recent searches dropdown).png b/design/marketplace-search/screens/wireframes/Focused (recent searches dropdown).png
new file mode 100644
index 0000000..c38efae
Binary files /dev/null and b/design/marketplace-search/screens/wireframes/Focused (recent searches dropdown).png differ
diff --git a/design/marketplace-search/screens/wireframes/Result page.png b/design/marketplace-search/screens/wireframes/Result page.png
new file mode 100644
index 0000000..e74558b
Binary files /dev/null and b/design/marketplace-search/screens/wireframes/Result page.png differ
diff --git a/design/marketplace-search/screens/wireframes/Results page (query submitted).png b/design/marketplace-search/screens/wireframes/Results page (query submitted).png
new file mode 100644
index 0000000..872344f
Binary files /dev/null and b/design/marketplace-search/screens/wireframes/Results page (query submitted).png differ
diff --git a/design/marketplace-search/screens/wireframes/Type head.png b/design/marketplace-search/screens/wireframes/Type head.png
new file mode 100644
index 0000000..f86da9e
Binary files /dev/null and b/design/marketplace-search/screens/wireframes/Type head.png differ
diff --git a/design/marketplace-search/screens/wireframes/Typeahead (2+ chars typed).png b/design/marketplace-search/screens/wireframes/Typeahead (2+ chars typed).png
new file mode 100644
index 0000000..f4fa14a
Binary files /dev/null and b/design/marketplace-search/screens/wireframes/Typeahead (2+ chars typed).png differ
diff --git a/design/marketplace-search/screens/wireframes/landing-1.png b/design/marketplace-search/screens/wireframes/landing-1.png
new file mode 100644
index 0000000..add4287
Binary files /dev/null and b/design/marketplace-search/screens/wireframes/landing-1.png differ
diff --git a/design/marketplace-search/screens/wireframes/landing.png b/design/marketplace-search/screens/wireframes/landing.png
new file mode 100644
index 0000000..bb9a31f
Binary files /dev/null and b/design/marketplace-search/screens/wireframes/landing.png differ
diff --git a/design/marketplace-search/search-flow.md b/design/marketplace-search/search-flow.md
new file mode 100644
index 0000000..98646ff
--- /dev/null
+++ b/design/marketplace-search/search-flow.md
@@ -0,0 +1,168 @@
+# 🔍 Marketplace Search UX Flow
+
+##  Overview
+This document defines the interaction flow for the **Marketplace Search system** in CommitLabs.
+
+The goal is to provide a **smooth, predictable, and helpful search experience** that supports discovery through typing, suggestions, and fallback states.
+
+---
+
+##  Entry Points
+Users can access search via:
+- Marketplace page (primary search bar)
+- Dashboard (global search)
+- Mobile header search icon
+
+---
+
+##  Search Interaction Flow
+
+### 1. Default State (Idle)
+- Search bar is visible with placeholder text:
+  > “Search commitments, tags, or categories”
+- Search icon is displayed inside input
+- No dropdown is visible
+
+---
+
+### 2. Focus State
+User clicks or taps the search bar:
+
+- Input becomes active
+- Cursor appears
+- Dropdown opens showing:
+  - Recent searches (if available)
+  - Suggested categories (optional)
+
+---
+
+### 3. Typing State
+User begins typing:
+
+- Real-time filtering begins
+- Dropdown updates dynamically
+- Show:
+  - Matching commitments
+  - Tags or categories
+  - Partial matches
+
+---
+
+### 4. Typeahead Suggestions
+Dropdown includes:
+
+#### Suggested Results
+- Commitment titles
+- Keywords or tags
+- Category labels
+
+#### Behavior
+- Highlight matched text
+- Limit results (e.g. top 5–8)
+- Scroll if overflow
+
+---
+
+### 5. Keyboard Interaction (Accessibility)
+- ↑ / ↓ → navigate suggestions
+- Enter → select highlighted result
+- Esc → close dropdown
+- Tab → move focus forward
+
+---
+
+### 6. Selection State
+User selects a result:
+
+- Navigate to selected item OR
+- Display filtered results page
+
+Search input updates with selected value
+
+---
+
+### 7. No Results State
+If no match is found:
+
+Display message:
+
+> “No results found for ‘[query]’”
+
+Provide fallback:
+- Suggest similar searches
+- Show popular or recommended items
+
+---
+
+### 8. Empty Search State
+If user focuses but hasn’t typed:
+
+Show:
+- Recent searches
+- Suggested categories
+- Popular searches
+
+---
+
+### 9. Clear / Reset
+User clicks clear (✕ icon):
+
+- Input is cleared
+- Dropdown resets to default suggestions
+
+---
+
+## 📱 Mobile Behavior
+
+### Mobile Search Entry
+- Tap search icon → expands to full-width input
+- Overlay or push-down layout
+
+### Mobile Interaction
+- Larger tap targets
+- Full-width dropdown
+- Keyboard does not block results
+
+### Mobile Close
+- “Cancel” button OR back navigation
+
+---
+
+##  Edge Cases
+
+### Network Delay
+- Show loading indicator in dropdown
+- Prevent flickering results
+
+### Error State
+Display message:
+
+> “Unable to load results. Please try again.”
+
+---
+
+##  UX Guidelines
+
+- Keep suggestions **relevant and limited**
+- Avoid overwhelming the user
+- Always provide **next steps**
+- Maintain consistent spacing and alignment
+- Ensure visibility of active/focused states
+
+---
+
+##  Design QA Checklist
+
+- Can users understand what to search?
+- Are suggestions helpful and accurate?
+- Is the “no results” state clear and useful?
+- Does mobile interaction feel natural?
+- Are keyboard interactions working correctly?
+- Is the experience consistent across screens?
+
+---
+
+##  Notes
+- Prioritize **speed and clarity over complexity**
+- Avoid advanced filters in initial interaction
+- Design should scale for future enhancements (filters, sorting)
\ No newline at end of file