From d2a044fbc60565c548edf88e8707412e9430375b Mon Sep 17 00:00:00 2001
From: Hwa-Seon LECOUEY <hLecouey@MacBookAir.lan>
Date: Thu, 28 May 2026 15:33:04 +0200
Subject: [PATCH] docs: add design.md and update CONTEXT.md

Add design.md with Figma source of truth, Bootstrap 5.3.3 DS identity,
desktop/mobile coverage status, usage hierarchy, Bootstrap customizations,
and accepted overrides section.

Remove design-related details from CONTEXT.md (Bootstrap description,
style separation) to avoid redundancy with design.md.
---
 CONTEXT.md |  2 +-
 design.md  | 44 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100644 design.md

diff --git a/CONTEXT.md b/CONTEXT.md
index fdb8fcad1..56b23e805 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -40,7 +40,7 @@ variables, or Symfony controllers/forms, you MUST refer to the main repository:
 - **CSS Preprocessor:** SCSS.
 - **CSS Methodology:** BEM (Block Element Modifier).
 - **Styling Framework:** Bootstrap (Heavily customized, separated from
-  PrestaShop core styles).
+  PrestaShop core styles). See `design.md` for design system and official Figma file.
 - **JavaScript:** Vanilla JavaScript & TypeScript (NO jQuery. jQuery is strictly
   forbidden).
 - **Build Tool:** Vite (Transitioning from Webpack).
diff --git a/design.md b/design.md
new file mode 100644
index 000000000..b0e0c2828
--- /dev/null
+++ b/design.md
@@ -0,0 +1,44 @@
+# Hummingbird — Design System
+
+## Source of Truth
+
+The Figma file is the visual reference for all Hummingbird components and pages.
+It is public and open to the community, agencies, and module developers without
+login.
+
+**Figma:** [HUMMINGBIRD — new](https://www.figma.com/design/ZlLqiOjTVXVlVu49sSsD8P/HUMMINGBIRD--new-?node-id=0-1)
+Access: public, read-only.
+
+The file is organized as follows:
+
+- **One Figma page per storefront page** — each contains a `DESKTOP` frame and
+  a `MOBILE` frame side by side.
+- **Components** — component library (atoms, molecules, organisms).
+- **Icons** — icon set.
+
+Storefront pages covered: Home, Product, Category, Cart, Checkout, Sign in,
+Contact, Stores, My account, 404.
+
+### Desktop vs. Mobile coverage
+
+| Version | Status | Notes |
+|---------|--------|-------|
+| Desktop ✅ | Complete | All storefront pages designed. Reference for implementation. |
+| Mobile 🏗️ | In progress | Frames exist for all pages but coverage is incomplete. Do not treat mobile frames as final — verify before implementing. |
+
+The Figma is the reference for new component design and for verifying visual
+regressions on desktop. For mobile, align with the desktop Figma intent and flag
+gaps rather than improvising.
+
+## Design System
+
+**Framework:** Bootstrap 5.3.3
+**Package:** `bootstrap` (npm)
+**Override layer:** `src/scss/bootstrap/overrides/` — Bootstrap variable overrides (loaded before Bootstrap core)
+
+Hummingbird does not ship a standalone design system. Bootstrap 5.3.3 is the
+design system. The theme's role is to customize it as little as possible while
+meeting PrestaShop storefront requirements.
+
+**Maturity:** Production — this is the shipped default theme for PrestaShop 9.1+.
+Visual regressions and accessibility regressions are treated as bugs.