From f64ae1d99319e7f7dba2eeb9e820e2fecb017d66 Mon Sep 17 00:00:00 2001
From: Saulo Padilha <saulo@tri.be>
Date: Tue, 14 Oct 2025 22:19:55 -0300
Subject: [PATCH 1/3] [MOOSE-156]: Consolidate navigation block styles and
 improve architecture

---
 .../blocks/tribe/mega-menu-item/style.pcss    |  92 +-------
 .../blocks/tribe/navigation-link/style.pcss   |  14 +-
 .../tribe/navigation-wrapper/style.pcss       | 210 +++++++++++++++++-
 .../tribe/standard-menu-item/style.pcss       | 198 +----------------
 4 files changed, 230 insertions(+), 284 deletions(-)

diff --git a/wp-content/themes/core/blocks/tribe/mega-menu-item/style.pcss b/wp-content/themes/core/blocks/tribe/mega-menu-item/style.pcss
index 8157ef50..5712129a 100644
--- a/wp-content/themes/core/blocks/tribe/mega-menu-item/style.pcss
+++ b/wp-content/themes/core/blocks/tribe/mega-menu-item/style.pcss
@@ -1,9 +1,11 @@
 /* -------------------------------------------------------------------------
  *
- * Block - Mega Navigation Menu - Styles - FE / Editor
+ * Block - Tribe Mega Menu Item
+ *
+ * Handles styling for mega menu dropdown content and wrapper.
+ * First-level navigation button styles are consolidated in Navigation Wrapper.
  *
  * ------------------------------------------------------------------------- */
-
 .wp-block-tribe-mega-menu-item {
 	color: var(--color-text);
 
@@ -32,92 +34,6 @@
 	}
 }
 
-/* mega menu item button toggle */
-.tribe-mega-menu-item__toggle {
-	background-color: transparent;
-	border: 0;
-	padding: var(--spacer-10) var(--spacer-30) var(--spacer-20) var(--spacer-10);
-	position: relative;
-	color: var(--color-text);
-	transition: var(--transition);
-
-	@media (--mq-navigation-max) {
-		width: 100%;
-		font-size: var(--font-size-40);
-		text-align: left;
-		padding-left: 0;
-	}
-
-	&::before {
-		content: "";
-		width: 0;
-		height: 4px;
-		background-color: var(--masthead-navigation-accent-color);
-		position: absolute;
-		bottom: -4px;
-		left: var(--spacer-10);
-		transition: width 0.15s ease-in-out;
-		z-index: 11;
-
-		@media (--mq-navigation-max) {
-			display: none;
-		}
-	}
-
-	&::after {
-		content: "";
-		background-color: currentcolor;
-		display: block;
-		height: 16px;
-		width: 10px;
-		mask: var(--icon-chevron-right) center no-repeat;
-		mask-size: contain;
-		position: absolute;
-		right: 2px;
-		top: calc(var(--spacer-10) + 5px);
-		transform: rotate(90deg);
-		transition: var(--transition);
-	}
-
-	&:hover,
-	&:active,
-	.menu-item-active & {
-		outline: none;
-		color: var(--masthead-navigation-accent-color);
-
-		&::before {
-			width: calc(100% - var(--spacer-10));
-		}
-
-		@media (--mq-navigation-max) {
-			outline: revert;
-			color: var(--color-text);
-		}
-	}
-
-	&:focus-visible {
-		outline: 2px solid var(--masthead-navigation-accent-color);
-	}
-
-	/*  Hide border on closed menu items, even when hovered or active */
-	:not(.menu-item-active) & {
-
-		@media (--mq-navigation-max) {
-
-			&::before {
-				width: 0;
-			}
-		}
-	}
-
-	.menu-item-active & {
-
-		&::after {
-			transform: rotate(-90deg);
-		}
-	}
-}
-
 /* enhanced menu pattern wrapper */
 .site-header__mega-menu-item-wrapper {
 	width: 100%;
diff --git a/wp-content/themes/core/blocks/tribe/navigation-link/style.pcss b/wp-content/themes/core/blocks/tribe/navigation-link/style.pcss
index 7e8449e0..7bde130b 100644
--- a/wp-content/themes/core/blocks/tribe/navigation-link/style.pcss
+++ b/wp-content/themes/core/blocks/tribe/navigation-link/style.pcss
@@ -1,16 +1,24 @@
 /* -------------------------------------------------------------------------
  *
- * Block - Tribe Navigation Link - Styles - FE / Editor
+ * Block - Tribe Navigation Link
+ *
+ * Handles individual link styling with base behavior:
+ * - Base link styles (underline, transitions, focus states)
+ * - Consistent styling across all navigation contexts
+ *
+ * Context-specific enhancements are handled in Navigation Wrapper.
  *
  * ------------------------------------------------------------------------- */
 
 .wp-block-tribe-navigation-link {
+	text-decoration: underline 1px;
 	text-decoration-color: transparent;
 	transition: var(--transition);
 	color: var(--color-text);
 	display: block;
 
 	&:hover,
+	&:active,
 	&:focus {
 		text-decoration-color: currentcolor;
 	}
@@ -18,8 +26,4 @@
 	&:focus-visible {
 		outline: 2px solid var(--masthead-navigation-accent-color);
 	}
-
-	.site-header__utility-menu & {
-		font-size: 14px;
-	}
 }
diff --git a/wp-content/themes/core/blocks/tribe/navigation-wrapper/style.pcss b/wp-content/themes/core/blocks/tribe/navigation-wrapper/style.pcss
index 2144df6b..053c31a0 100644
--- a/wp-content/themes/core/blocks/tribe/navigation-wrapper/style.pcss
+++ b/wp-content/themes/core/blocks/tribe/navigation-wrapper/style.pcss
@@ -1,8 +1,16 @@
-/* -------------------------------------------------------------------------
+/*
+ * Block - Tribe Navigation Wrapper
  *
- * Block - Tribe Navigation Wrapper - Styles - FE / Editor
+ * Central navigation styling coordinator that handles:
+ * - Semantic <nav> wrapper with ARIA support
+ * - Consolidated toggle button styles (mega menu & standard menu)
+ * - First-level navigation styling with animated underlines
+ * - Context-specific styles for Primary vs Utility menus
+ * - Responsive behavior and mobile adaptations
  *
- * ------------------------------------------------------------------------- */
+ * This block acts as the styling foundation for all navigation components.
+ *
+ */
 
 .wp-block-tribe-navigation-wrapper {
 	align-self: center;
@@ -16,3 +24,199 @@
 		}
 	}
 }
+
+/*
+ * TOGGLE BUTTON STYLES
+ *
+ * Consolidated styles for both mega menu and standard menu toggle buttons.
+ * Handles base styling, chevron icons, and responsive behavior.
+ */
+.tribe-standard-menu-item__toggle,
+.tribe-mega-menu-item__toggle {
+	background-color: transparent;
+	border: 0;
+	padding: var(--spacer-10) var(--spacer-20) var(--spacer-10) var(--spacer-10);
+	position: relative;
+	color: var(--color-text);
+	transition: var(--transition);
+	font-size: var(--font-size-20);
+	text-decoration-color: transparent;
+
+	&:is(.tribe-mega-menu-item__toggle) {
+		padding: var(--spacer-10) var(--spacer-30) var(--spacer-20) var(--spacer-10);
+
+		@media (--mq-navigation-max) {
+			font-size: var(--font-size-40);
+		}
+	}
+
+	@media (--mq-navigation-max) {
+		width: 100%;
+		text-align: left;
+		padding-left: 0;
+	}
+
+	&::after {
+		content: "";
+		background-color: currentcolor;
+		display: block;
+		height: 16px;
+		width: 10px;
+		mask: var(--icon-chevron-right) center no-repeat;
+		mask-size: contain;
+		position: absolute;
+		right: 2px;
+		top: calc(var(--spacer-10) + 5px);
+		transform: rotate(90deg);
+		transition: var(--transition);
+	}
+
+	.menu-item-active & {
+
+		&::after {
+			transform: rotate(-90deg);
+		}
+	}
+
+	.site-header__navigation & {
+
+		&:hover,
+		&:active,
+		.menu-item-active & {
+			outline: none;
+			color: var(--masthead-navigation-accent-color);
+
+			@media (--mq-navigation-max) {
+				outline: revert;
+				color: var(--color-text);
+			}
+		}
+
+		&::after {
+			height: 16px;
+			width: 10px;
+		}
+	}
+
+	/* Utility Menu */
+	.site-header__utility-menu & {
+
+		&:hover,
+		&:focus-visible,
+		.menu-item-active & {
+			text-decoration-color: currentcolor;
+			color: currentcolor;
+
+			.tribe-standard-menu-item__toggle-label {
+				border-bottom-color: currentcolor;
+			}
+		}
+
+		&::after {
+			height: 12px;
+			width: 6px;
+
+			@media (--mq-navigation-max) {
+				position: relative;
+				left: auto;
+				top: auto;
+				display: inline-block;
+				margin-left: var(--spacer-20);
+			}
+		}
+	}
+}
+
+/*
+ * PRIMARY NAVIGATION FIRST-LEVEL STYLES
+ *
+ * Unified styling for all first-level navigation items in the primary menu:
+ * - Mega Menu toggles
+ * - Standard Menu toggles
+ * - Navigation Links
+ *
+ * Features animated underlines that expand on hover/active states.
+ */
+.site-header__navigation {
+
+	/* Target first-level navigation items */
+	.tribe-mega-menu-item__toggle,
+	& .wp-block-tribe-standard-menu-item .tribe-standard-menu-item__toggle,
+	& > li > .wp-block-tribe-navigation-link {
+		padding: var(--spacer-10) var(--spacer-30) var(--spacer-20) var(--spacer-10);
+		font-size: var(--font-size-20);
+		text-decoration: none;
+		outline-offset: 0;
+
+		@media (--mq-navigation-max) {
+			font-size: var(--font-size-40);
+			padding-left: 0;
+		}
+
+		/* Animated underline that grows on hover */
+		&::before {
+			content: "";
+			width: 0;
+			height: 4px;
+			background-color: var(--masthead-navigation-accent-color);
+			position: absolute;
+			bottom: -4px;
+			left: var(--spacer-10);
+			transition: width 0.15s ease-in-out;
+			z-index: 11;
+
+			/* Hide underline on mobile */
+			@media (--mq-navigation-max) {
+				display: none;
+			}
+		}
+
+		&:focus-visible {
+			outline: 2px solid var(--masthead-navigation-accent-color);
+		}
+
+		/* Expand underline on hover, active state, or when menu item is active */
+		&:hover,
+		&:active,
+		.menu-item-active & {
+
+			&::before {
+				width: calc(100% - var(--spacer-10));
+			}
+		}
+
+		/* Tribe Navigation Links lack chevrons, so center underline with equal padding */
+		&:is(.wp-block-tribe-navigation-link) {
+			padding: var(--spacer-10) var(--spacer-10) var(--spacer-20)
+				var(--spacer-10);
+
+			@media (--mq-navigation-max) {
+				font-size: var(--font-size-40);
+				padding-left: 0;
+			}
+
+			&:hover,
+			&:active,
+			.menu-item-active & {
+
+				&::before {
+					width: calc(100% - (2 * var(--spacer-10)));
+				}
+			}
+		}
+	}
+}
+
+/*
+ * UTILITY MENU STYLES
+ *
+ * Specific styling overrides for utility menu navigation items.
+ * Generally smaller and simpler than primary navigation.
+ */
+.site-header__utility-menu {
+
+	& .wp-block-tribe-standard-menu-item .tribe-standard-menu-item__toggle,
+	& > li .wp-block-tribe-navigation-link {
+		font-size: 14px;
+	}
+}
diff --git a/wp-content/themes/core/blocks/tribe/standard-menu-item/style.pcss b/wp-content/themes/core/blocks/tribe/standard-menu-item/style.pcss
index c3eb3b15..60cfe5fa 100644
--- a/wp-content/themes/core/blocks/tribe/standard-menu-item/style.pcss
+++ b/wp-content/themes/core/blocks/tribe/standard-menu-item/style.pcss
@@ -1,198 +1,18 @@
 /* -------------------------------------------------------------------------
  *
- * Block - Standard Navigation Item - Styles - FE / Editor
+ * Block - Tribe Standard Menu Item
+ *
+ * Handles standard menu item specific styling:
+ * - Basic positioning and layout
+ * - Toggle label styling (underline on hover)
+ * - Submenu wrapper positioning and behavior
+ *
+ * First-level navigation button styles are consolidated in Navigation Wrapper.
  *
  * ------------------------------------------------------------------------- */
 
 .wp-block-tribe-standard-menu-item {
 	position: relative;
-
-	> a.wp-block-tribe-navigation-link {
-		padding: var(--spacer-10);
-		font-size: 14px;
-		text-decoration-color: transparent;
-		text-underline-offset: 3px;
-
-		@media (--mq-navigation-max) {
-			padding: var(--spacer-10) 0;
-		}
-
-		&:hover,
-		&:active,
-		&:focus {
-			text-decoration-color: currentcolor;
-
-
-			@media (--mq-navigation-max) {
-				text-decoration: none;
-			}
-		}
-	}
-
-	.site-header__navigation > & > a {
-		font-size: var(--font-size-20);
-		display: block;
-		background-color: transparent;
-		border: 0;
-		padding: var(--spacer-10) var(--spacer-10) var(--spacer-20);
-		position: relative;
-		color: var(--color-text);
-		transition: var(--transition);
-		text-decoration: none;
-		outline-offset: 0;
-
-		@media (--mq-navigation-max) {
-			font-size: var(--font-size-40);
-			padding-inline: 0;
-		}
-
-		&::before {
-			content: "";
-			width: 0;
-			height: 4px;
-			background-color: var(--masthead-navigation-accent-color);
-			position: absolute;
-			bottom: -4px;
-			left: var(--spacer-10);
-			transition: width 0.15s ease-in-out;
-			z-index: 11;
-		}
-
-		&:hover,
-		&:active {
-			outline: none;
-			color: var(--masthead-navigation-accent-color);
-
-			&::before {
-				width: calc(100% - (2 * var(--spacer-10)));
-			}
-
-			@media (--mq-navigation-max) {
-				outline: revert;
-				color: var(--color-text);
-
-				&::before {
-					width: 0;
-				}
-			}
-		}
-	}
-}
-
-/* standard menu item button toggle */
-.tribe-standard-menu-item__toggle {
-	background-color: transparent;
-	border: 0;
-	padding: var(--spacer-10) var(--spacer-20) var(--spacer-10) var(--spacer-10);
-	position: relative;
-	color: var(--color-text);
-	transition: var(--transition);
-	font-size: 14px;
-	text-decoration-color: transparent;
-
-	@media (--mq-navigation-max) {
-		width: 100%;
-		text-align: left;
-		padding-left: 0;
-	}
-
-	&::after {
-		content: "";
-		background-color: currentcolor;
-		display: block;
-		height: 12px;
-		width: 6px;
-		mask: var(--icon-chevron-right) center no-repeat;
-		mask-size: contain;
-		position: absolute;
-		right: 2px;
-		top: calc(var(--spacer-10) + 5px);
-		transform: rotate(90deg);
-		transition: var(--transition);
-
-		@media (--mq-navigation-max) {
-			position: relative;
-			left: auto;
-			top: auto;
-			display: inline-block;
-			margin-left: var(--spacer-20);
-		}
-	}
-
-	&:hover,
-	&:focus-visible,
-	.menu-item-active & {
-		text-decoration-color: currentcolor;
-		color: currentcolor;
-
-		.tribe-standard-menu-item__toggle-label {
-			border-bottom-color: currentcolor;
-		}
-	}
-
-	.menu-item-active & {
-
-		&::after {
-			transform: rotate(-90deg);
-		}
-	}
-
-	/* CASE: Standard menu item added to the Primary Menu */
-
-	/* TODO: @frontend refactor this so we can target standard menu item regardless of primary or utility menu use */
-	.site-header__navigation > .wp-block-tribe-standard-menu-item & {
-		text-decoration: none;
-		padding: var(--spacer-10) var(--spacer-30) var(--spacer-20) var(--spacer-10);
-
-		@mixin t-body;
-
-		@media (--mq-navigation-max) {
-			width: 100%;
-			text-align: left;
-			padding-left: 0;
-		}
-
-		&::before {
-			content: "";
-			width: 0;
-			height: 4px;
-			background-color: var(--masthead-navigation-accent-color);
-			position: absolute;
-			bottom: -1px;
-			left: var(--spacer-10);
-			transition: width 0.15s ease-in-out;
-			z-index: 11;
-
-			@media (--mq-navigation-max) {
-				left: 0;
-				transition-duration: 0.25s;
-			}
-		}
-
-		&::after {
-			height: 16px;
-			width: 10px;
-			right: 2px;
-		}
-
-		&:hover,
-		&:focus-visible,
-		.menu-item-active & {
-			text-decoration: none;
-			color: var(--masthead-navigation-accent-color);
-
-			&::before {
-				width: calc(100% - var(--spacer-10));
-			}
-
-			@media (--mq-navigation-max) {
-
-				&::before {
-					width: 100%;
-				}
-			}
-		}
-	}
 }
 
 .tribe-standard-menu-item__toggle-label {
@@ -219,6 +39,7 @@
 		display: flex;
 	}
 
+	/* Align it from the right */
 	@media (--mq-navigation) {
 		position: absolute;
 		right: 0;
@@ -233,6 +54,7 @@
 	/* CASE: Standard menu item added to the Primary Menu */
 	.site-header__navigation > .wp-block-tribe-standard-menu-item & {
 
+		/* Align it from the left */
 		@media (--mq-navigation) {
 			right: auto;
 			left: var(--spacer-10);

From f0fd6da850e01d6d98c3f91de82262131fcd1442 Mon Sep 17 00:00:00 2001
From: Saulo Padilha <saulo@tri.be>
Date: Tue, 14 Oct 2025 23:22:52 -0300
Subject: [PATCH 2/3] [MOOSE-156]: Update documentation

---
 docs/navigation-blocks.md | 129 ++++++++++++++++++++++++++++++++++----
 1 file changed, 116 insertions(+), 13 deletions(-)

diff --git a/docs/navigation-blocks.md b/docs/navigation-blocks.md
index d8eb3fac..4361f14b 100644
--- a/docs/navigation-blocks.md
+++ b/docs/navigation-blocks.md
@@ -8,13 +8,30 @@ The site navigation system is built using a collection of custom WordPress block
 
 ### Block Hierarchy
 
-The navigation system consists of four main blocks that work together:
+The navigation system consists of four main blocks that work together with a centralized styling approach:
 
-1. **Navigation Wrapper** (`tribe/navigation-wrapper`) - Structural container
+1. **Navigation Wrapper** (`tribe/navigation-wrapper`) - Central styling coordinator and structural container
 2. **Mega Menu Item** (`tribe/mega-menu-item`) - Complex dropdown menus
 3. **Standard Menu Item** (`tribe/standard-menu-item`) - Simple menu items with optional dropdowns
 4. **Navigation Link** (`tribe/navigation-link`) - Individual link items
 
+### CSS Architecture
+
+The styling architecture follows a centralized coordinator pattern:
+
+**Navigation Wrapper** acts as the central styling coordinator that handles:
+- Consolidated toggle button styles (shared between mega and standard menu items)
+- First-level navigation styling with animated underlines
+- Context-specific behavior for Primary vs Utility menus
+- Responsive adaptations and mobile behavior
+
+**Individual Blocks** handle only their specific content:
+- **Navigation Link**: Base link styling only
+- **Mega Menu Item**: Dropdown container and content styling
+- **Standard Menu Item**: Basic positioning and submenu wrapper styling
+
+This architecture eliminates code duplication and creates a single source of truth for navigation styling.
+
 
 ## HTML Structure & Implementation
 
@@ -102,16 +119,24 @@ The navigation system consists of four main blocks that work together:
 
 ### 1. Navigation Wrapper (`tribe/navigation-wrapper`)
 
-**Purpose**: A structural block that wraps menu items in a semantic `<nav>` tag with no added styles.
+**Purpose**: Central styling coordinator that provides semantic structure and handles all first-level navigation styling.
 
 **Location**: `wp-content/themes/core/blocks/tribe/navigation-wrapper/`
 
 **Features**:
 - Provides semantic HTML structure with `<nav>` element
 - Supports `aria-label` attribute for accessibility
-- No visual styling (purely structural)
-- Supports inner blocks and alignment
-- Acts as a container for menu items
+- **Consolidated toggle button styling** for both mega and standard menu items
+- **Unified first-level navigation styling** with animated underlines
+- **Context-aware styling** for Primary vs Utility menu placement
+- Responsive behavior and mobile adaptations
+- Acts as the styling foundation for all navigation components
+
+**Styling Responsibilities**:
+- Toggle button styles (chevrons, padding, hover states)
+- First-level navigation item styling (fonts, colors, underlines)
+- Context-specific overrides for different menu types
+- Mobile responsive adaptations
 
 **Attributes**:
 - `ariaLabel` (string) - Accessible label for the navigation
@@ -125,7 +150,7 @@ The navigation system consists of four main blocks that work together:
 
 ### 2. Mega Menu Item (`tribe/mega-menu-item`)
 
-**Purpose**: Enhanced dropdown menus with rich content capabilities for complex navigation structures.
+**Purpose**: Handles mega menu dropdown content and container functionality.
 
 **Location**: `wp-content/themes/core/blocks/tribe/mega-menu-item/`
 
@@ -133,9 +158,14 @@ The navigation system consists of four main blocks that work together:
 - Configurable menu toggle label
 - Uses pattern template (`patterns/mega-dropdown`) for consistent content structure
 - Supports complex layouts and rich content within dropdowns
+- **Container queries** for responsive dropdown layouts
 - JavaScript interactions for opening/closing mega menus
 - Event-driven architecture with custom events
-- Full width layouts and grid alignment support
+
+**Styling Scope**:
+- **Dropdown content styling only** (first-level button styling handled by Navigation Wrapper)
+- Container queries for responsive layouts
+- Mega menu wrapper positioning and background
 
 **Attributes**:
 - `menuToggleLabel` (string) - Text label for the top-level navigation button
@@ -152,7 +182,7 @@ The navigation system consists of four main blocks that work together:
 
 ### 3. Standard Menu Item (`tribe/standard-menu-item`)
 
-**Purpose**: Simple menu items with optional dropdown functionality for basic navigation needs.
+**Purpose**: Handles basic menu item positioning and submenu wrapper functionality.
 
 **Location**: `wp-content/themes/core/blocks/tribe/standard-menu-item/`
 
@@ -160,9 +190,14 @@ The navigation system consists of four main blocks that work together:
 - Toggle for enabling simple dropdown submenus
 - Only allows `tribe/navigation-link` as child blocks
 - Configurable menu toggle label when used as dropdown
-- Lightweight alternative to mega menu items
+- **Lightweight positioning and layout** (first-level styling handled by Navigation Wrapper)
 - Perfect for simple link lists
 
+**Styling Scope**:
+- **Basic positioning and layout only** (first-level button styling handled by Navigation Wrapper)
+- Toggle label styling (underline on hover)
+- Submenu wrapper positioning and behavior
+
 **Attributes**:
 - `hasSubMenu` (boolean) - Enables dropdown functionality
 - `menuToggleLabel` (string) - Text label when used as dropdown toggle
@@ -176,7 +211,7 @@ The navigation system consists of four main blocks that work together:
 
 ### 4. Navigation Link (`tribe/navigation-link`)
 
-**Purpose**: Individual link items within menu structures.
+**Purpose**: Provides base link styling with consistent behavior across all navigation contexts.
 
 **Location**: `wp-content/themes/core/blocks/tribe/navigation-link/`
 
@@ -184,8 +219,12 @@ The navigation system consists of four main blocks that work together:
 - Rich text editing for link text
 - URL configuration with WordPress LinkControl component
 - Target/new window option
-- Can only be used as child of `tribe/standard-menu-item`
-- Proper link management with unlink functionality
+- **Base link styling only** (context-specific enhancements handled by Navigation Wrapper)
+- Consistent foundation across all menu types
+
+**Styling Scope**:
+- **Base link styles only**: underline, transitions, focus states
+- Context-specific styling (Primary vs Utility menu) handled by Navigation Wrapper
 
 **Attributes**:
 - `text` (string) - Link text content
@@ -200,6 +239,46 @@ The navigation system consists of four main blocks that work together:
 - Link control popover for URL management
 - Toolbar controls for link/unlink actions
 
+## Styling Architecture
+
+### Centralized Coordinator Pattern
+
+The navigation system uses a **centralized coordinator pattern** where the Navigation Wrapper acts as the central styling authority:
+
+```
+Navigation Wrapper (Coordinator)
+├── Toggle Button Styles (shared by mega & standard menu items)
+├── First-Level Navigation Styling (animated underlines, hover states)
+├── Context-Specific Overrides (Primary vs Utility menu)
+└── Responsive Adaptations (mobile behavior)
+
+Individual Blocks (Content-Specific)
+├── Navigation Link: Base link styles only
+├── Mega Menu Item: Dropdown container & content
+└── Standard Menu Item: Basic positioning & submenu wrapper
+```
+
+### Key Benefits
+
+**Eliminates Code Duplication**: Shared styles are defined once in Navigation Wrapper
+**Single Source of Truth**: Navigation behavior modifications happen in one place
+**Clear Separation**: Each block has a specific, well-defined styling responsibility
+**Easy Maintenance**: Changes to navigation styling require updates to only one file
+**Consistent Experience**: Unified first-level navigation behavior across all menu types
+
+### CSS File Organization
+
+**Navigation Wrapper** (`navigation-wrapper/style.pcss`):
+- Toggle button styles (consolidated)
+- Primary navigation first-level styles
+- Utility menu style overrides
+- Responsive behavior
+
+**Individual Block Files**:
+- **Navigation Link**: Base link foundation only
+- **Mega Menu Item**: Dropdown content and container queries
+- **Standard Menu Item**: Simple positioning and submenu wrapper
+
 ## JavaScript Architecture
 
 ### Event System
@@ -259,6 +338,30 @@ The navigation system integrates with:
 - Focus management for dropdown interactions
 - Screen reader friendly markup
 
+## Development Guidelines
+
+### Working with the Centralized Architecture
+
+#### **Making Navigation Styling Changes**
+
+**For First-Level Navigation Changes**: Edit `navigation-wrapper/style.pcss`
+- Toggle button styling (padding, colors, hover states)
+- Animated underlines and transitions
+- Font sizes and spacing
+- Context-specific behavior (Primary vs Utility)
+
+**For Individual Block Content**: Edit respective block files
+- `navigation-link/style.pcss`: Base link foundation only
+- `mega-menu-item/style.pcss`: Dropdown content and container queries
+- `standard-menu-item/style.pcss`: Basic positioning and submenu wrapper
+
+### Customization Points
+
+- **Navigation Wrapper**: Central coordinator for all first-level styling
+- **Patterns**: Modify `patterns/mega-dropdown` for mega menu layouts
+- **Individual Blocks**: Content-specific styling only
+- **Context Selectors**: Use `.site-header__navigation` and `.site-header__utility-menu` for targeting
+
 ## File Structure
 
 ```

From c89724eddd337132422b9c914d5e7e26370198fd Mon Sep 17 00:00:00 2001
From: Saulo Padilha <saulo@tri.be>
Date: Tue, 14 Oct 2025 23:23:14 -0300
Subject: [PATCH 3/3] [MOOSE-156]: Hide standard menu item wrapper in the
 editor

---
 .../themes/core/blocks/tribe/standard-menu-item/editor.pcss   | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/wp-content/themes/core/blocks/tribe/standard-menu-item/editor.pcss b/wp-content/themes/core/blocks/tribe/standard-menu-item/editor.pcss
index 1105a518..4cca9295 100644
--- a/wp-content/themes/core/blocks/tribe/standard-menu-item/editor.pcss
+++ b/wp-content/themes/core/blocks/tribe/standard-menu-item/editor.pcss
@@ -31,4 +31,8 @@
 	.site-header__utility-menu &:not(:only-child) {
 		display: none;
 	}
+
+	.site-header__navigation & {
+		display: none !important;
+	}
 }